@eventcatalog/core 5.8.0 → 5.9.1

package/eventcatalog/src/features/tools/catalog-tools.ts

@@ -11,7 +11,12 @@ import {
   processSpecifications,
   versionMatches,
 } from '@utils/collections/util';
-import { getUbiquitousLanguageWithSubdomains } from '@utils/collections/domains';
+import {
+  getDomains,
+  getTermsDefinedInSeveralDomains,
+  getUbiquitousLanguageGlossary,
+  getUbiquitousLanguageWithSubdomains,
+} from '@utils/collections/domains';
 import { getAbsoluteFilePathForAstroFile } from '@utils/files';
 import fs from 'node:fs';
 import { getArchitectureDiagramGraph } from '@utils/node-graphs/architecture-diagram';
@@ -910,12 +915,71 @@ export async function findMessageBySchemaId(params: {
 // Ubiquitous Language (DDD)
 // ============================================
 
+const toUbiquitousLanguageTermResult = (
+  term: any,
+  domain: { id: string; name: string },
+  isDuplicate: boolean,
+  parentDomainId?: string
+) => ({
+  id: term.id,
+  term: term.name,
+  summary: term.summary,
+  description: term.description || term.summary,
+  icon: term.icon,
+  domainId: domain.id,
+  domainName: domain.name,
+  ...(parentDomainId ? { isSubdomain: true, parentDomainId } : {}),
+  isDuplicate,
+});
+
 /**
- * Get ubiquitous language terms for a domain (including subdomains)
- * Returns the domain's language/glossary if defined
+ * Get ubiquitous language terms, optionally filtered to the terms matching `term`.
+ * With a domainId, returns that domain's terms and its subdomains' terms.
+ * Without one, returns the terms of every domain (paginated), keeping each domain's meaning of a term separate.
  */
-export async function explainUbiquitousLanguageTerms(params: { domainId: string; domainVersion?: string }) {
-  const domains = await getCollection('domains');
+export async function explainUbiquitousLanguageTerms(params: {
+  domainId?: string;
+  domainVersion?: string;
+  term?: string;
+  cursor?: string;
+}) {
+  const search = params.term?.trim().toLowerCase();
+  const matchesSearch = (term: { id: string; term: string }) =>
+    !search || term.term.toLowerCase().includes(search) || term.id.toLowerCase().includes(search);
+
+  if (!params.domainId) {
+    const glossary = await getUbiquitousLanguageGlossary();
+    const definedInSeveralDomains = getTermsDefinedInSeveralDomains(glossary);
+    const isDuplicate = (term: { name: string }) => definedInSeveralDomains.has(term.name.toLowerCase());
+
+    const terms = glossary
+      .flatMap((domain) => [
+        ...domain.terms.map((term) => toUbiquitousLanguageTermResult(term, domain, isDuplicate(term))),
+        ...domain.subdomains.flatMap((subdomain) =>
+          subdomain.terms.map((term) => toUbiquitousLanguageTermResult(term, subdomain, isDuplicate(term), subdomain.parentId))
+        ),
+      ])
+      .filter(matchesSearch);
+
+    const page = paginate(terms, params.cursor);
+    if ('error' in page) return page;
+
+    return {
+      terms: page.items,
+      nextCursor: page.nextCursor,
+      totalCount: page.totalCount,
+      duplicateTerms: Array.from(new Set(page.items.filter((term) => term.isDuplicate).map((term) => term.term.toLowerCase()))),
+      message:
+        terms.length === 0
+          ? search
+            ? `No ubiquitous language terms match "${params.term}"`
+            : 'No ubiquitous language terms are defined in this catalog'
+          : undefined,
+    };
+  }
+
+  // getDomains resolves subdomains to their entries, which is what finds the subdomains' terms
+  const domains = await getDomains({ getAllVersions: true });
 
   // Use the existing utility to find the domain by id and version (or latest)
   const matches = getItemsFromCollectionByIdAndSemverOrLatest(domains, params.domainId, params.domainVersion);
@@ -930,31 +994,32 @@ export async function explainUbiquitousLanguageTerms(params: { domainId: string;
   // Get ubiquitous language including subdomains
   const ubiquitousLanguageData = await getUbiquitousLanguageWithSubdomains(domain as any);
   const { domain: domainUL, subdomains, duplicateTerms } = ubiquitousLanguageData;
+  const domainName = (domain.data as any).name || params.domainId;
 
   // 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()),
-    })) || [];
+  const domainTerms = (domainUL?.data?.dictionary || [])
+    .map((term: any) =>
+      toUbiquitousLanguageTermResult(
+        term,
+        { id: params.domainId!, name: domainName },
+        duplicateTerms.has(term.name.toLowerCase())
+      )
+    )
+    .filter(matchesSearch);
 
   // 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 subdomainTerms = subdomains
+    .flatMap(({ subdomain, ubiquitousLanguage }) =>
+      (ubiquitousLanguage?.data?.dictionary || []).map((term: any) =>
+        toUbiquitousLanguageTermResult(
+          term,
+          { id: (subdomain.data as any).id, name: (subdomain.data as any).name || (subdomain.data as any).id },
+          duplicateTerms.has(term.name.toLowerCase()),
+          params.domainId
+        )
+      )
+    )
+    .filter(matchesSearch);
 
   const allTerms = [...domainTerms, ...subdomainTerms];
 
@@ -962,8 +1027,10 @@ export async function explainUbiquitousLanguageTerms(params: { domainId: string;
     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',
+      domainName,
+      message: search
+        ? `No ubiquitous language terms match "${params.term}" in this domain or its subdomains`
+        : 'No ubiquitous language terms defined for this domain or its subdomains',
       terms: [],
       subdomainCount: subdomains.length,
     };
@@ -972,7 +1039,7 @@ export async function explainUbiquitousLanguageTerms(params: { domainId: string;
   return {
     domainId: params.domainId,
     domainVersion: (domain.data as any).version,
-    domainName: (domain.data as any).name || params.domainId,
+    domainName,
     terms: allTerms,
     totalCount: allTerms.length,
     domainTermCount: domainTerms.length,
@@ -1359,7 +1426,7 @@ export const toolDescriptions = {
   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.',
+    "Use this tool to find out what a business term means, or to get the ubiquitous language (Domain-Driven Design glossary) of a domain or of every domain. Pass domainId for a domain's terms and its subdomains' terms, term to find a term by name, or neither for the whole glossary. The same term can mean different things in different domains: each domain's meaning is returned separately and duplicates are flagged.",
   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:

package/eventcatalog/src/pages/docs/llm/llms.txt.ts

@@ -3,7 +3,7 @@ import config from '@config';
 import type { APIRoute } from 'astro';
 
 import { isLLMSTxtEnabled } from '@utils/feature';
-import { getUbiquitousLanguage } from '@utils/collections/domains';
+import { getTermSummary, getUbiquitousLanguage } from '@utils/collections/domains';
 import { getResourceDocs } from '@utils/collections/resource-docs';
 
 const events = await getCollection('events');
@@ -32,8 +32,8 @@ const ubiquitousLanguages: Record<string, { id: string; version: string; propert
 for (const domain of domains) {
   const ubiquitousLanguagesForDomain = await getUbiquitousLanguage(domain);
   if (ubiquitousLanguagesForDomain.length > 0) {
-    ubiquitousLanguages[domain.id] = ubiquitousLanguagesForDomain.map((item) => ({
-      id: domain.id,
+    ubiquitousLanguages[domain.data.id] = ubiquitousLanguagesForDomain.map((item) => ({
+      id: domain.data.id,
       version: domain.data.version,
       properties: item.data.dictionary,
     }));
@@ -44,15 +44,15 @@ for (const domain of domains) {
 const renderUbiquitousLanguages = (baseUrl: string) => {
   return Object.entries(ubiquitousLanguages)
     .map(([domainId, items]) => {
-      const domainName = domains.find((domain) => domain.id === domainId)?.data.name || domainId;
+      const domainName = domains.find((domain) => domain.data.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)`
-            )
+            .map(([key, value]: any) => {
+              const summary = getTermSummary(value);
+              return `    - [${value.name}${summary ? `: - ${summary}` : ''}](${baseUrl}/docs/domains/${domainId}/language.mdx)`;
+            })
             .join('\n');
           return propertiesList;
         })
@@ -93,7 +93,8 @@ export const GET: APIRoute = async ({ params, request }) => {
 
   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 summary = item.data.summary?.trim();
+    return `- [${item.data.name} - ${item.data.id} - ${item.data.version} ${params ? `- ${params}` : ''}](${baseUrl}/docs/${type}/${item.data.id}/${item.data.version}.mdx) ${summary ? `- ${summary}` : ''}`;
   };
 
   const formatSimpleItem = (item: any, type: string) =>
@@ -136,19 +137,19 @@ export const GET: APIRoute = async ({ params, request }) => {
     `# ${config.organizationName} EventCatalog Documentation\n`,
     `> ${config.tagline}\n`,
     '## Events',
-    events.map((item) => formatVersionedItem(item, 'events')).join(''),
+    events.map((item) => formatVersionedItem(item, 'events')).join('\n'),
     '\n## Commands',
-    commands.map((item) => formatVersionedItem(item, 'commands')).join(''),
+    commands.map((item) => formatVersionedItem(item, 'commands')).join('\n'),
     '\n## Queries',
-    queries.map((item) => formatVersionedItem(item, 'queries')).join(''),
+    queries.map((item) => formatVersionedItem(item, 'queries')).join('\n'),
     '\n## Agents',
-    agents.map((item) => formatVersionedItem(item, 'agents')).join(''),
+    agents.map((item) => formatVersionedItem(item, 'agents')).join('\n'),
     '\n## Services',
-    services.map((item) => formatVersionedItem(item, 'services')).join(''),
+    services.map((item) => formatVersionedItem(item, 'services')).join('\n'),
     '\n## Data Products',
     dataProducts.map((item) => formatVersionedItem(item, 'data-products')).join('\n'),
     '\n## Domains',
-    domains.map((item) => formatVersionedItem(item, 'domains')).join(''),
+    domains.map((item) => formatVersionedItem(item, 'domains')).join('\n'),
     '\n## Flows',
     flows.map((item) => formatVersionedItem(item, 'flows')).join('\n'),
     '\n## Channels',
@@ -156,8 +157,14 @@ export const GET: APIRoute = async ({ params, request }) => {
       .map((item) =>
         formatVersionedItem(item, 'channels', item.data.protocols?.map((protocol) => `protocol - ${protocol}`).join('&'))
       )
-      .join(''),
-    ...(Object.keys(ubiquitousLanguages).length > 0 ? ['## Ubiquitous Language', renderUbiquitousLanguages(baseUrl)] : []),
+      .join('\n'),
+    ...(Object.keys(ubiquitousLanguages).length > 0
+      ? [
+          '\n## Ubiquitous Language',
+          `The whole glossary, with terms defined in more than one domain listed together: ${baseUrl}/docs/llm/ubiquitous-language.txt`,
+          renderUbiquitousLanguages(baseUrl),
+        ]
+      : []),
     '\n## Containers (Databases, External Systems)',
     containers.map((item) => formatVersionedItem(item, 'containers')).join('\n'),
     '\n## Entities',

package/eventcatalog/src/pages/docs/llm/schemas.txt.ts

@@ -52,7 +52,7 @@ export const GET: APIRoute = async ({ params, request }) => {
 
   const formatVersionedItem = (item: (typeof schemas)[number]) => {
     const message = item.data.message;
-    return `- [${message.name || message.id} - ${message.id} - ${message.version}](${baseUrl}/api/schemas/${message.collectionName}/${message.id}/${message.version})} ${message.summary ? `- ${message.summary.trim()}` : ''}`;
+    return `- [${message.name || message.id} - ${message.id} - ${message.version}](${baseUrl}/api/schemas/${message.collectionName}/${message.id}/${message.version}) ${message.summary ? `- ${message.summary.trim()}` : ''}`;
   };
 
   const formatServiceWithSchema = (item: ServiceWithSchema) => {

package/eventcatalog/src/pages/docs/llm/ubiquitous-language.txt.ts

@@ -0,0 +1,68 @@
+import config from '@config';
+import type { APIRoute } from 'astro';
+import { isLLMSTxtEnabled } from '@utils/feature';
+import {
+  getTermsDefinedInSeveralDomains,
+  getTermSummary,
+  getUbiquitousLanguageGlossary,
+  type DomainGlossary,
+  type UbiquitousLanguageTerm,
+} from '@utils/collections/domains';
+
+const formatTerm = (term: UbiquitousLanguageTerm) => {
+  const summary = getTermSummary(term);
+  return `- ${term.name}${summary ? `: ${summary}` : ''}`;
+};
+
+export const GET: APIRoute = async ({ request }) => {
+  if (!isLLMSTxtEnabled()) {
+    return new Response('ubiquitous-language.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 glossary = await getUbiquitousLanguageGlossary();
+
+  const header = [
+    `# ${config.organizationName} Ubiquitous Language`,
+    '> The business terms used across this organization, grouped by domain. A term only applies within its domain: the same word can mean something different in another domain.',
+  ].join('\n');
+
+  if (glossary.length === 0) {
+    return new Response(`${header}\n\nNo ubiquitous language terms are defined in this catalog.`, {
+      headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+    });
+  }
+
+  const formatDomain = (domain: DomainGlossary, heading: string) =>
+    [
+      `${heading} ${domain.name}`,
+      ...(domain.terms.length > 0
+        ? [`Full definitions: ${baseUrl}/docs/domains/${domain.id}/language.mdx`, ...domain.terms.map(formatTerm)]
+        : []),
+    ].join('\n');
+
+  const termsInSeveralDomains = [...getTermsDefinedInSeveralDomains(glossary).values()].map((definitions) =>
+    [
+      `- ${definitions[0].term.name}`,
+      ...definitions.map(({ domain, term }) => {
+        const summary = getTermSummary(term);
+        return `  - ${domain.name}${summary ? `: ${summary}` : ''}`;
+      }),
+    ].join('\n')
+  );
+
+  const sections = [
+    header,
+    ...(termsInSeveralDomains.length > 0 ? [`## Terms defined in more than one domain\n${termsInSeveralDomains.join('\n')}`] : []),
+    ...glossary.flatMap((domain) => [
+      formatDomain(domain, '##'),
+      ...domain.subdomains.map((subdomain) => formatDomain(subdomain, '###')),
+    ]),
+  ];
+
+  return new Response(sections.join('\n\n'), {
+    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+  });
+};

package/eventcatalog/src/pages/settings/llm-access.astro

@@ -16,6 +16,7 @@ const apiBase = buildUrl('/api/settings');
 const llmsTxtUrl = buildUrl('/llms.txt');
 const llmsFullTxtUrl = buildUrl('/llms-full.txt');
 const schemasTxtUrl = buildUrl('/docs/llm/schemas.txt');
+const ubiquitousLanguageTxtUrl = buildUrl('/docs/llm/ubiquitous-language.txt');
 ---
 
 <SettingsLayout title="LLM Access" active="llm-access">
@@ -27,5 +28,6 @@ const schemasTxtUrl = buildUrl('/docs/llm/schemas.txt');
     llmsTxtUrl={llmsTxtUrl}
     llmsFullTxtUrl={llmsFullTxtUrl}
     schemasTxtUrl={schemasTxtUrl}
+    ubiquitousLanguageTxtUrl={ubiquitousLanguageTxtUrl}
   />
 </SettingsLayout>

package/eventcatalog/src/utils/catalog-modules.ts

@@ -0,0 +1,16 @@
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/**
+ * The file:// URL of a file in the catalog. Node's ES module loader only takes URLs: on Windows an absolute path
+ * (C:\catalog\eventcatalog.auth.js) reads as a URL with the scheme "c:", and the import fails.
+ */
+export const catalogModuleUrl = (file: string, directory = process.env.PROJECT_DIR || process.cwd()) =>
+  pathToFileURL(join(directory, file)).href;
+
+/**
+ * Imports a module from the catalog (eventcatalog.auth.js, eventcatalog.chat.js, middleware.ts), at runtime rather
+ * than bundled into the build, so the catalog's own file is the one that runs.
+ */
+export const importCatalogModule = (file: string, directory?: string) =>
+  import(/* @vite-ignore */ catalogModuleUrl(file, directory));

package/eventcatalog/src/utils/collections/domains.ts

@@ -436,6 +436,90 @@ export const getRootDomains = async (): Promise<Domain[]> => {
   return domains.filter((d) => !allSubDomains.some((sd) => sd.data.id === d.data.id));
 };
 
+export type UbiquitousLanguageTerm = NonNullable<UbiquitousLanguage['data']['dictionary']>[number];
+
+export type DomainGlossary = {
+  id: string;
+  version: string;
+  name: string;
+  terms: UbiquitousLanguageTerm[];
+};
+
+export type SubdomainGlossary = DomainGlossary & { parentId: string };
+
+export type OrganizationGlossaryDomain = DomainGlossary & { subdomains: SubdomainGlossary[] };
+
+/**
+ * The ubiquitous language of the whole catalog: every domain with terms (or with a subdomain that has
+ * them), with all of its subdomains, at any depth, listed under it. Terms stay with their domain and are
+ * never merged, because the same word can mean something different in another domain.
+ */
+export const getUbiquitousLanguageGlossary = async (): Promise<OrganizationGlossaryDomain[]> => {
+  const [domains, rootDomains, ubiquitousLanguages] = await Promise.all([
+    getDomains({ getAllVersions: false }),
+    getRootDomains(),
+    getCollection('ubiquitousLanguages'),
+  ]);
+  const domainsById = new Map(domains.map((domain) => [domain.data.id, domain]));
+
+  const toGlossary = (domain: Domain): DomainGlossary => ({
+    id: domain.data.id,
+    version: domain.data.version,
+    name: domain.data.name || domain.data.id,
+    terms: getUbiquitousLanguageFromCollection(domain, ubiquitousLanguages).flatMap(
+      (ubiquitousLanguage) => ubiquitousLanguage.data.dictionary || []
+    ),
+  });
+
+  // Each domain is only listed once, whether several domains share it or domains point at each other
+  const listedDomains = new Set<string>();
+
+  const getDescendants = (parent: Domain): SubdomainGlossary[] =>
+    ((parent.data.domains as unknown as Domain[]) || []).flatMap((subdomain) => {
+      if (listedDomains.has(subdomain.data.id)) return [];
+      listedDomains.add(subdomain.data.id);
+
+      // Use the current version even when the parent pins an old one: only current versions have glossaries,
+      // and their own subdomains resolved
+      const currentSubdomain = domainsById.get(subdomain.data.id) || subdomain;
+
+      return [{ ...toGlossary(currentSubdomain), parentId: parent.data.id }, ...getDescendants(currentSubdomain)];
+    });
+
+  // Root domains go first. Any domain still not listed after them points in a loop, so has no root.
+  return [...rootDomains, ...domains]
+    .flatMap((domain) => {
+      if (listedDomains.has(domain.data.id)) return [];
+      listedDomains.add(domain.data.id);
+
+      return [
+        {
+          ...toGlossary(domain),
+          subdomains: getDescendants(domain).filter((subdomain) => subdomain.terms.length > 0),
+        },
+      ];
+    })
+    .filter((domain) => domain.terms.length > 0 || domain.subdomains.length > 0);
+};
+
+/** The terms defined in more than one domain, keyed by their lowercase name */
+export const getTermsDefinedInSeveralDomains = (glossary: OrganizationGlossaryDomain[]) => {
+  const definitions = new Map<string, { domain: DomainGlossary; term: UbiquitousLanguageTerm }[]>();
+
+  for (const domain of glossary.flatMap((domain) => [domain, ...domain.subdomains])) {
+    for (const term of domain.terms) {
+      const key = term.name.toLowerCase();
+      definitions.set(key, [...(definitions.get(key) || []), { domain, term }]);
+    }
+  }
+
+  return new Map([...definitions].filter(([, termDefinitions]) => new Set(termDefinitions.map((d) => d.domain.id)).size > 1));
+};
+
+/** A term's definition on one line, for the text files we generate for LLMs */
+export const getTermSummary = (term: UbiquitousLanguageTerm) =>
+  (term.summary || term.description || '').replace(/\s+/g, ' ').trim();
+
 export const getDomainsForService = async (service: Service): Promise<Domain[]> => {
   const domains = await getDomains({ getAllVersions: false });
   return domains.filter((d) => {

package/package.json

@@ -7,7 +7,7 @@
   },
   "license": "BUSL-1.1",
   "type": "module",
-  "version": "5.8.0",
+  "version": "5.9.1",
   "publishConfig": {
     "access": "public"
   },
@@ -144,7 +144,7 @@
     "@eventcatalog/exporters": "0.1.4",
     "@eventcatalog/fitness": "0.1.1",
     "@eventcatalog/sdk": "2.32.0",
-    "@eventcatalog/visualiser": "^5.2.4",
+    "@eventcatalog/visualiser": "^5.2.5",
     "@eventcatalog/linter": "1.3.1"
   },
   "devDependencies": {

package/dist/docs/development/ask-your-architecture/04-agents/01-overview.md

@@ -1,27 +0,0 @@
----
-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.

package/dist/docs/development/ask-your-architecture/04-agents/02-code-to-docs.md

@@ -1,124 +0,0 @@
----
-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.