@eventcatalog/core 4.9.0 → 4.10.0

package/eventcatalog/src/components/SideNav/NestedSideBar/storage.ts

@@ -1,4 +1,4 @@
-import type { SectionCollapsePreferences } from './utils';
+import { createSectionCollapsePreferences, type SectionCollapsePreferences } from './utils';
 
 // ============================================
 // Local Storage Persistence
@@ -7,6 +7,7 @@ import type { SectionCollapsePreferences } from './utils';
 const STORAGE_KEY = 'eventcatalog-sidebar-nav';
 const SECTION_PREFERENCES_KEY = 'eventcatalog-sidebar-sections:v2';
 const FAVORITES_KEY = 'eventcatalog-sidebar-favorites';
+const SCROLL_KEY = 'eventcatalog-sidebar-scroll';
 
 // ============================================
 // Types
@@ -47,13 +48,59 @@ export const loadState = (): PersistedState | null => {
   }
 };
 
+// ============================================
+// Scroll position
+// ============================================
+
+/**
+ * The sidebar remounts on every full page load, which resets its scroll offset to the
+ * top. Persist offsets (per tab) so the list looks stationary when you follow a link near
+ * the bottom. A capped map keyed by drill-down path, so scrolling one level doesn't lose
+ * another level's offset (root -> drill in -> scroll -> back keeps the root position).
+ */
+const MAX_SCROLL_ENTRIES = 30;
+
+export const saveScrollPosition = (pathKey: string, scrollTop: number): void => {
+  try {
+    const stored = sessionStorage.getItem(SCROLL_KEY);
+    const parsed = stored ? JSON.parse(stored) : {};
+    const offsets: Record<string, number> = parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    // Re-insert so the map stays ordered by recency, then drop the oldest beyond the cap.
+    delete offsets[pathKey];
+    offsets[pathKey] = scrollTop;
+    const keys = Object.keys(offsets);
+    for (const stale of keys.slice(0, Math.max(0, keys.length - MAX_SCROLL_ENTRIES))) {
+      delete offsets[stale];
+    }
+    sessionStorage.setItem(SCROLL_KEY, JSON.stringify(offsets));
+  } catch (e) {
+    console.warn('Failed to save sidebar scroll position:', e);
+  }
+};
+
+export const loadScrollPosition = (pathKey: string): number | null => {
+  try {
+    const stored = sessionStorage.getItem(SCROLL_KEY);
+    if (!stored) return null;
+    const offsets = JSON.parse(stored);
+    const scrollTop = offsets && typeof offsets === 'object' ? offsets[pathKey] : undefined;
+    return typeof scrollTop === 'number' ? scrollTop : null;
+  } catch (e) {
+    console.warn('Failed to load sidebar scroll position:', e);
+    return null;
+  }
+};
+
 // ============================================
 // Collapsed Sections
 // ============================================
 
 export const saveCollapsedSections = (preferences: SectionCollapsePreferences): void => {
   try {
-    localStorage.setItem(SECTION_PREFERENCES_KEY, JSON.stringify({ expanded: [...preferences.expanded] }));
+    localStorage.setItem(
+      SECTION_PREFERENCES_KEY,
+      JSON.stringify({ expanded: [...preferences.expanded], collapsed: [...preferences.collapsed] })
+    );
   } catch (e) {
     console.warn('Failed to save collapsed sections:', e);
   }
@@ -64,15 +111,16 @@ export const loadCollapsedSections = (): SectionCollapsePreferences => {
     const stored = localStorage.getItem(SECTION_PREFERENCES_KEY);
     if (stored) {
       const preferences = JSON.parse(stored);
-      return {
-        expanded: new Set(Array.isArray(preferences.expanded) ? preferences.expanded : []),
-      };
+      return createSectionCollapsePreferences(
+        Array.isArray(preferences.expanded) ? preferences.expanded : [],
+        Array.isArray(preferences.collapsed) ? preferences.collapsed : []
+      );
     }
 
-    return { expanded: new Set() };
+    return createSectionCollapsePreferences();
   } catch (e) {
     console.warn('Failed to load collapsed sections:', e);
-    return { expanded: new Set() };
+    return createSectionCollapsePreferences();
   }
 };
 

package/eventcatalog/src/components/SideNav/NestedSideBar/utils.spec.ts

@@ -1,30 +1,40 @@
 import { describe, expect, it } from 'vitest';
-import { canCollapseGroup, findNodeKeyByUrl, getGroupLabel, isGroupCollapsed } from './utils';
+import {
+  canCollapseGroup,
+  createSectionCollapsePreferences,
+  findNodeKeyByUrl,
+  getDefaultCollapsedState,
+  isGroupCollapsed,
+  toggleGroupCollapsed,
+} from './utils';
 
-const preferences = (expanded: string[] = []) => ({
-  expanded: new Set(expanded),
-});
+const preferences = (expanded: string[] = [], collapsed: string[] = []) => createSectionCollapsePreferences(expanded, collapsed);
 
 describe('sidebar group presentation', () => {
-  it('includes the visible child count in the group label', () => {
-    expect(getGroupLabel('Outbound Messages', 10)).toBe('Outbound Messages (10)');
+  it('keeps root-level groups expanded', () => {
+    expect(canCollapseGroup(true)).toBe(false);
   });
 
-  it.each(['Quick Reference', 'Architecture', 'Resources'])('does not include the child count for %s', (title) => {
-    expect(getGroupLabel(title, 10)).toBe(title);
+  it('lets every group inside a resource sidebar collapse, whatever its size', () => {
+    expect(canCollapseGroup(false)).toBe(true);
+    expect(canCollapseGroup(false)).toBe(true);
   });
 
-  it('keeps top-level groups expanded', () => {
-    expect(canCollapseGroup(6, true)).toBe(false);
+  it('keeps groups marked as non-collapsible expanded regardless of their size', () => {
+    expect(canCollapseGroup(false, false)).toBe(false);
   });
 
-  it('only allows nested groups with more than five children to collapse', () => {
-    expect(canCollapseGroup(5, false)).toBe(false);
-    expect(canCollapseGroup(6, false)).toBe(true);
+  it('starts long lists collapsed and short ones open unless told otherwise', () => {
+    expect(getDefaultCollapsedState(5)).toBe(false);
+    expect(getDefaultCollapsedState(6)).toBe(true);
+    expect(getDefaultCollapsedState(6, false)).toBe(false);
+    expect(getDefaultCollapsedState(2, true)).toBe(true);
   });
 
-  it('keeps groups marked as non-collapsible expanded regardless of their size', () => {
-    expect(canCollapseGroup(100, false, false)).toBe(false);
+  it('always allows collapsing when an explicit collapsed state is set, overriding every other rule', () => {
+    expect(canCollapseGroup(false, true, true)).toBe(true);
+    expect(canCollapseGroup(false, true, false)).toBe(true);
+    expect(canCollapseGroup(true, false, true)).toBe(true);
   });
 });
 
@@ -40,6 +50,40 @@ describe('isGroupCollapsed', () => {
   it('uses an explicit expanded preference', () => {
     expect(isGroupCollapsed(true, 'outbound-messages', preferences(['outbound-messages']))).toBe(false);
   });
+
+  it('starts expanded when the group defaults to expanded, until the user collapses it', () => {
+    expect(isGroupCollapsed(true, 'owners', preferences(), false)).toBe(false);
+    expect(isGroupCollapsed(true, 'owners', preferences([], ['owners']), false)).toBe(true);
+  });
+});
+
+describe('toggleGroupCollapsed', () => {
+  it('records the user overriding a collapsed-by-default group, then clears it on the way back', () => {
+    const opened = toggleGroupCollapsed('g', preferences());
+    expect([...opened.expanded]).toEqual(['g']);
+    expect(opened.collapsed.size).toBe(0);
+
+    const closedAgain = toggleGroupCollapsed('g', opened);
+    expect(closedAgain.expanded.size).toBe(0);
+    expect([...closedAgain.collapsed]).toEqual(['g']);
+  });
+
+  it('records the user overriding an expanded-by-default group', () => {
+    const closed = toggleGroupCollapsed('g', preferences(), false);
+    expect([...closed.collapsed]).toEqual(['g']);
+    expect(isGroupCollapsed(true, 'g', closed, false)).toBe(true);
+
+    const reopened = toggleGroupCollapsed('g', closed, false);
+    expect(reopened.collapsed.size).toBe(0);
+    expect([...reopened.expanded]).toEqual(['g']);
+  });
+
+  it('does not mutate the previous preferences', () => {
+    const before = preferences();
+    toggleGroupCollapsed('g', before);
+    expect(before.expanded.size).toBe(0);
+    expect(before.collapsed.size).toBe(0);
+  });
 });
 
 describe('findNodeKeyByUrl', () => {

package/eventcatalog/src/components/SideNav/NestedSideBar/utils.ts

@@ -1,20 +1,66 @@
 // Shared utilities for NestedSideBar components
 
 export const SIDEBAR_GROUP_COLLAPSE_THRESHOLD = 5;
-const GROUP_TITLES_WITHOUT_COUNT = new Set(['Quick Reference', 'Architecture', 'Resources']);
 
+/**
+ * The user's overrides of each group's default collapse state, keyed by group id.
+ * A group is in at most one set; absence means "use the group's default".
+ */
 export type SectionCollapsePreferences = {
   expanded: Set<string>;
+  collapsed: Set<string>;
+};
+
+export const createSectionCollapsePreferences = (
+  expanded: Iterable<string> = [],
+  collapsed: Iterable<string> = []
+): SectionCollapsePreferences => ({
+  expanded: new Set(expanded),
+  collapsed: new Set(collapsed),
+});
+
+/**
+ * Whether a group shows a caret and can be toggled. Every group inside a resource's sidebar
+ * can collapse (docs-sidebar behaviour); the root catalog level stays open. An explicit
+ * `collapsed` (set via sidebar.json) overrides every other rule, including `collapsible: false`.
+ */
+export const canCollapseGroup = (isTopLevel: boolean, collapsible = true, collapsed?: boolean): boolean => {
+  if (collapsed !== undefined) return true;
+  return collapsible && !isTopLevel;
 };
 
-export const canCollapseGroup = (childCount: number, isTopLevel: boolean, collapsible = true): boolean =>
-  collapsible && !isTopLevel && childCount > SIDEBAR_GROUP_COLLAPSE_THRESHOLD;
+/**
+ * The state a group starts in before the user touches it: an explicit `collapsed` wins,
+ * otherwise long lists start collapsed and short ones start open.
+ */
+export const getDefaultCollapsedState = (childCount: number, collapsed?: boolean): boolean =>
+  collapsed ?? childCount > SIDEBAR_GROUP_COLLAPSE_THRESHOLD;
 
-export const getGroupLabel = (title: string, childCount: number): string =>
-  GROUP_TITLES_WITHOUT_COUNT.has(title) ? title : `${title} (${childCount})`;
+export const isGroupCollapsed = (
+  canCollapse: boolean,
+  groupId: string,
+  preferences: SectionCollapsePreferences,
+  defaultCollapsed = true
+): boolean => {
+  if (!canCollapse) return false;
+  if (preferences.expanded.has(groupId)) return false;
+  if (preferences.collapsed.has(groupId)) return true;
+  return defaultCollapsed;
+};
 
-export const isGroupCollapsed = (canCollapse: boolean, groupId: string, preferences: SectionCollapsePreferences): boolean => {
-  return canCollapse && !preferences.expanded.has(groupId);
+/** Flip a group's state, recording it as an override of its default. */
+export const toggleGroupCollapsed = (
+  groupId: string,
+  preferences: SectionCollapsePreferences,
+  defaultCollapsed = true
+): SectionCollapsePreferences => {
+  const next = createSectionCollapsePreferences(preferences.expanded, preferences.collapsed);
+  const isCurrentlyCollapsed = isGroupCollapsed(true, groupId, preferences, defaultCollapsed);
+  next.expanded.delete(groupId);
+  next.collapsed.delete(groupId);
+  if (isCurrentlyCollapsed) next.expanded.add(groupId);
+  else next.collapsed.add(groupId);
+  return next;
 };
 
 /**

package/eventcatalog/src/content.config.ts

@@ -1199,6 +1199,73 @@ const schemas = defineCollection({
     .extend(baseSchema.shape),
 });
 
+// Optional `sidebar.json` next to a resource's index.mdx. When present it fully
+// replaces the generated sidebar for that resource (see stores/sidebar-store/custom-sidebar.ts).
+const sidebarLinkSchema = z
+  .object({
+    title: z.string(),
+    href: z.string(),
+    icon: z.string().optional(),
+  })
+  .strict();
+
+// { "title": "Runbooks", "icon": "Siren", "collapsed": true, "pages": [...] } (custom group).
+// Groups nest: a page can itself be a group, rendered as a subsection.
+type SidebarGroupInput = {
+  title: string;
+  icon?: string;
+  collapsed?: boolean;
+  pages: Array<string | z.input<typeof sidebarLinkSchema> | SidebarGroupInput>;
+};
+const sidebarGroupSchema: z.ZodType<SidebarGroupInput> = z.lazy(() =>
+  z
+    .object({
+      title: z.string(),
+      icon: z.string().optional(),
+      collapsed: z.boolean().optional(),
+      // "$quick-reference", "[[service|OrderService@1.0.0]]", "[[doc|guides/sla]]", { title, href } or a nested group
+      pages: z.array(z.union([z.string(), sidebarLinkSchema, sidebarGroupSchema])),
+    })
+    .strict()
+);
+
+const sidebarSchema = z
+  .object({
+    $schema: z.string().optional(),
+    sections: z.array(
+      z.union([
+        // "$quick-reference" (predefined section)
+        z.string(),
+        // { "section": "$owners", "title": "Team", "collapsed": false } (predefined section, adjusted)
+        z
+          .object({
+            section: z.string(),
+            title: z.string().optional(),
+            icon: z.string().optional(),
+            collapsed: z.boolean().optional(),
+          })
+          .strict(),
+        sidebarGroupSchema,
+      ])
+    ),
+  })
+  .strict();
+
+const sidebars = defineCollection({
+  loader: globWithSafeWatcher({
+    // Anchored to the resource roots (like resourceDocCategories) so an unrelated
+    // sidebar.json elsewhere in the project — or the public/generated mirror — is ignored.
+    pattern: withIgnoredBuildArtifacts(
+      withFederatedContent([
+        '{services,events,commands,queries,flows,containers,channels,entities,data-products,systems,agents,adrs}/**/sidebar.json',
+        'domains/**/sidebar.json',
+      ])
+    ),
+    base: projectDirBase,
+  }),
+  schema: sidebarSchema,
+});
+
 export const collections = {
   events,
   commands,
@@ -1236,4 +1303,7 @@ export const collections = {
 
   // Generated from message schema references
   schemas,
+
+  // Optional per-resource sidebar overrides (sidebar.json)
+  sidebars,
 };

package/eventcatalog/src/enterprise/collections/resource-docs-utils.ts

@@ -71,6 +71,25 @@ type InferredResource = {
   resourceVersion: string;
 };
 
+const DOC_TYPE_LABELS: Record<string, string> = {
+  adrs: 'ADR',
+  runbooks: 'Runbook',
+  contracts: 'Contract',
+  troubleshooting: 'Troubleshooting',
+  guides: 'Guide',
+};
+
+/** Human label for a doc type folder, e.g. `guides` → "Guide", `release-notes` → "Release Notes". */
+export const getResourceDocTypeLabel = (type: string): string => {
+  if (DOC_TYPE_LABELS[type]) return DOC_TYPE_LABELS[type];
+  const normalized = type
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+  return normalized || 'Doc';
+};
+
 let memoryCache: ResourceDocEntry[] | null = null;
 let memoryCategoryCache: ResourceDocCategoryEntry[] | null = null;
 let memoryResourceLookupCache: Record<ResourceCollection, ResourceLookup> | null = null;

package/eventcatalog/src/enterprise/fields/pages/fields.astro

@@ -1,4 +1,6 @@
 ---
+// Visualiser styles ship in the page head so ClientRouter navigations keep them (see NodeGraph.astro).
+import '@eventcatalog/visualiser/styles-core.css';
 import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
 import FieldsExplorer from '@components/FieldsExplorer/FieldsExplorer';
 import { isEventCatalogScaleEnabled } from '@utils/feature';

package/eventcatalog/src/pages/architecture/[type]/[id]/[version]/index.astro

@@ -24,7 +24,7 @@ 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))]">
+      <div class="w-full min-w-0 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 />}
         {

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/[docType]/[docId]/[docVersion]/index.astro

@@ -8,7 +8,8 @@ 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 { isEventCatalogChatEnabled, isMarkdownDownloadEnabled, isResourceDocsEnabled } from '@utils/feature';
+import { getResourceDocTypeLabel } from '@utils/collections/resource-docs';
 import { getIcon } from '@utils/badges';
 import { collectionToResourceMap } from '@utils/collections/util';
 
@@ -51,28 +52,28 @@ const pagefindAttributes =
 <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 class="w-full min-w-0 lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
+        {/* Header mirrors the latest-doc page ([docId]/index.astro) and the resource page. */}
+        <div class="border-b border-[rgb(var(--ec-page-border))] md:pb-3 pt-4">
+          <div class="flex flex-col gap-4">
+            <span class="text-xs md:text-sm font-semibold text-[rgb(var(--ec-accent))] capitalize">
+              {getResourceDocTypeLabel(props.data.type)}
+            </span>
+            <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 pt-2 text-[rgb(var(--ec-page-text-muted))] font-light">{props.data.summary}</p>
+              <p class="text-base pt-4 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">
+              <div class="flex flex-wrap gap-1.5 pt-4">
                 {badges.map((badge: any) => <Badge badge={badge} />)}
               </div>
             )
           }
-          <div class="pt-4">
+          <div class="pt-5">
             <CopyAsMarkdown
               client:only="react"
               variant="toolbar"
@@ -80,9 +81,9 @@ const pagefindAttributes =
               chatQuery={chatQuery}
               chatEnabled={chatEnabled}
               editUrl=""
-              markdownDownloadEnabled={true}
+              markdownDownloadEnabled={isMarkdownDownloadEnabled()}
               rssFeedEnabled={false}
-              preferChatAsDefault={false}
+              preferChatAsDefault={chatEnabled}
             />
           </div>
         </div>
@@ -100,7 +101,7 @@ const pagefindAttributes =
             )
           }
         </div>
-        <div class="prose py-4 max-w-none">
+        <div class="prose prose-md pt-8 pb-4 w-full text-[15px]">
           <Content components={components(props)} />
         </div>
       </div>

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/[docType]/[docId]/index.astro

@@ -8,9 +8,10 @@ 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 { isEventCatalogChatEnabled, isMarkdownDownloadEnabled, isResourceDocsEnabled } from '@utils/feature';
 import { getIcon } from '@utils/badges';
 import { collectionToResourceMap } from '@utils/collections/util';
+import { getResourceDocTypeLabel } from '@utils/collections/resource-docs';
 
 import { Page } from './_index.data';
 
@@ -36,6 +37,7 @@ const docsBasePath = `/docs/${props.data.resourceCollection}/${props.data.resour
 const singularResourceName =
   collectionToResourceMap[props.data.resourceCollection as keyof typeof collectionToResourceMap] ??
   props.data.resourceCollection.slice(0, props.data.resourceCollection.length - 1);
+const typeLabel = getResourceDocTypeLabel(props.data.type);
 const chatEnabled = isEventCatalogChatEnabled();
 const chatQuery = `Tell me about the ${props.data.type} doc "${title}" for ${props.data.resourceId} (version ${props.data.version})`;
 
@@ -51,20 +53,22 @@ const pagefindAttributes =
 <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="w-full min-w-0 lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
+        {/* Header mirrors the resource page (docs/[type]/[id]/[version]/index.astro) so docs feel like part of the resource. */}
+        <div class="border-b border-[rgb(var(--ec-page-border))] md:pb-3 pt-4">
           <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>
-              )
-            }
+            <span class="text-xs md:text-sm font-semibold text-[rgb(var(--ec-accent))] capitalize">{typeLabel}</span>
+            <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 pt-4 text-[rgb(var(--ec-page-text-muted))] font-light">{props.data.summary}</p>}
+          {
+            badges.length > 0 && (
+              <div class="flex flex-wrap gap-1.5 pt-4">
+                {badges.map((badge: any) => <Badge badge={badge} />)}
+              </div>
+            )
+          }
+          <div class="pt-5">
             <CopyAsMarkdown
               client:only="react"
               variant="toolbar"
@@ -72,9 +76,9 @@ const pagefindAttributes =
               chatQuery={chatQuery}
               chatEnabled={chatEnabled}
               editUrl=""
-              markdownDownloadEnabled={true}
+              markdownDownloadEnabled={isMarkdownDownloadEnabled()}
               rssFeedEnabled={false}
-              preferChatAsDefault={false}
+              preferChatAsDefault={chatEnabled}
             />
           </div>
         </div>
@@ -92,7 +96,7 @@ const pagefindAttributes =
             )
           }
         </div>
-        <div class="prose py-4 max-w-none">
+        <div class="prose prose-md pt-8 pb-4 w-full text-[15px]">
           <Content components={components(props)} />
         </div>
       </div>

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/graphql/[filename].astro

@@ -66,7 +66,7 @@ const pagefindAttributes =
 <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="w-full min-w-0 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">

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/index.astro

@@ -408,8 +408,8 @@ if (!isAdrPage && !hasCurrentFlowEmbed && !hasCurrentPageNodeGraph) {
 <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 class="w-full min-w-0 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-3 pt-4">
           <div>
             <div>
               <div class="flex flex-col gap-4">
@@ -447,7 +447,7 @@ if (!isAdrPage && !hasCurrentFlowEmbed && !hasCurrentPageNodeGraph) {
               </div>
             </div>
 
-            <h2 class="text-base pt-4 text-[rgb(var(--ec-page-text-muted))] font-light">{props.data.summary}</h2>
+            <p class="text-base pt-4 text-[rgb(var(--ec-page-text-muted))] font-light">{props.data.summary}</p>
             {
               badges && (
                 <div class="flex flex-wrap gap-1.5 pt-4">
@@ -596,7 +596,7 @@ if (!isAdrPage && !hasCurrentFlowEmbed && !hasCurrentPageNodeGraph) {
           }
         </div>
 
-        <div class="prose prose-md py-4 w-full text-[15px]">
+        <div class="prose prose-md pt-8 pb-4 w-full text-[15px]">
           <Content components={components(props)} />
         </div>
         <div data-pagefind-ignore>

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/resources/index.astro

@@ -29,6 +29,8 @@ const hrefForResource = (collection: SystemResourceCollection, id: string, versi
   return buildUrl(`/docs/${collection}/${id}/${version}`);
 };
 
+const ownerTypeLabel = ownerCollection === 'domains' ? 'Domain' : 'System';
+
 const resources: SystemResourceItem[] = resourceGroups.flatMap(({ collection, items }) =>
   items.map((item: any) => ({
     collection,
@@ -45,16 +47,22 @@ const resources: SystemResourceItem[] = resourceGroups.flatMap(({ collection, it
 <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 class="w-full min-w-0 lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
+        {/* Header mirrors the resource page (docs/[type]/[id]/[version]/index.astro). */}
+        <div class="border-b border-[rgb(var(--ec-page-border))] md:pb-3 pt-4">
+          <div class="flex flex-col gap-4">
+            <span class="text-xs md:text-sm font-semibold text-[rgb(var(--ec-accent))] capitalize">{ownerTypeLabel}</span>
+            <h2 id="doc-page-header" class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">
+              {data.name} Resources
+            </h2>
+          </div>
+          <p class="text-base pt-4 pb-1 text-[rgb(var(--ec-page-text-muted))] font-light">
+            {resources.length} {resources.length === 1 ? 'resource' : 'resources'} mapped to the {data.name}{' '}
+            {ownerTypeLabel.toLowerCase()}.
+          </p>
         </div>
 
-        <div class="py-8 w-full">
+        <div class="pt-8 pb-4 w-full">
           <SystemResourcesTable resources={resources} client:only="react" />
         </div>
       </div>