diff --git a/calm-hub-ui/src/admin/panels/EntitlementsPanel.test.tsx b/calm-hub-ui/src/admin/panels/EntitlementsPanel.test.tsx
index cf361038e..ee2cae5c6 100644
--- a/calm-hub-ui/src/admin/panels/EntitlementsPanel.test.tsx
+++ b/calm-hub-ui/src/admin/panels/EntitlementsPanel.test.tsx
@@ -192,7 +192,9 @@ describe('EntitlementsPanel', () => {
             await waitFor(() =>
                 expect(screen.getByRole('region', { name: /global admin access/i })).toBeInTheDocument()
             );
-            expect(userAccessSvc.getNamespaceUserAccess).toHaveBeenCalledWith('GLOBAL');
+            await waitFor(() =>
+                expect(userAccessSvc.getNamespaceUserAccess).toHaveBeenCalledWith('GLOBAL')
+            );
         });
     });
 
diff --git a/calm-hub-ui/src/hub/components/diagram-section/DiagramSection.tsx b/calm-hub-ui/src/hub/components/diagram-section/DiagramSection.tsx
index 0abcc03cf..355da682f 100644
--- a/calm-hub-ui/src/hub/components/diagram-section/DiagramSection.tsx
+++ b/calm-hub-ui/src/hub/components/diagram-section/DiagramSection.tsx
@@ -87,7 +87,7 @@ export function DiagramSection({ data, onItemSelect, hasDetailsPanel, breadcrumb
         [nodeSearchTerm, nodeTypeFilter, nodeTypes]
     );
     const calmService = useMemo(() => new CalmService(), []);
-    const defaultLayoutState = useDefaultLayout(data.name, data.id, data.calmType);
+    const defaultLayoutState = useDefaultLayout(data.name, data.id, data.calmType, data.data as Record<string, unknown> | undefined);
     // Destructured locals so handleSaveLayout/handleResetLayout below can depend
     // on exactly the (already useCallback-stable) functions they call, rather
     // than the whole result object — which still changes identity whenever
@@ -428,6 +428,26 @@ export function DiagramSection({ data, onItemSelect, hasDetailsPanel, breadcrumb
     const showLayoutActions = !comparing && activeTab === 'diagram';
     const layoutActions = showLayoutActions && (
         <div className="flex items-center gap-1">
+            {defaultLayoutState.hasBothSources && (
+                <div className="join" role="group" aria-label="Layout source">
+                    <button
+                        type="button"
+                        className={`join-item btn btn-xs ${defaultLayoutState.layoutSource === 'document' || (defaultLayoutState.layoutSource === 'auto' && defaultLayoutState.documentLayout) ? 'btn-active' : ''}`}
+                        onClick={() => defaultLayoutState.setLayoutSource('document')}
+                        title="Use layout from document"
+                    >
+                        Document
+                    </button>
+                    <button
+                        type="button"
+                        className={`join-item btn btn-xs ${defaultLayoutState.layoutSource === 'server' || (defaultLayoutState.layoutSource === 'auto' && !defaultLayoutState.documentLayout) ? 'btn-active' : ''}`}
+                        onClick={() => defaultLayoutState.setLayoutSource('server')}
+                        title="Use saved layout from server"
+                    >
+                        Saved
+                    </button>
+                </div>
+            )}
             {canSaveLayout && (
                 <button
                     type="button"
diff --git a/calm-hub-ui/src/hub/hooks/useDefaultLayout.test.tsx b/calm-hub-ui/src/hub/hooks/useDefaultLayout.test.tsx
index da7689cb6..24a82203c 100644
--- a/calm-hub-ui/src/hub/hooks/useDefaultLayout.test.tsx
+++ b/calm-hub-ui/src/hub/hooks/useDefaultLayout.test.tsx
@@ -184,7 +184,7 @@ describe('useDefaultLayout', () => {
                 5,
                 expect.objectContaining({
                     for: '/api/calm/namespaces/finos/architectures/5',
-                    pins: [{ 'unique-id': 'node-a', position: { x: 1, y: 2 } }],
+                    nodes: { 'node-a': { x: 1, y: 2 } },
                 }),
                 'architectures'
             );
@@ -312,11 +312,101 @@ describe('useDefaultLayout', () => {
                 9,
                 expect.objectContaining({
                     for: '/api/calm/namespaces/finos/patterns/9',
-                    pins: [{ 'unique-id': 'node-a', position: { x: 1, y: 2 } }],
+                    nodes: { 'node-a': { x: 1, y: 2 } },
                 }),
                 'patterns'
             );
             expect(result.current.defaultLayout).toEqual(positions);
         });
     });
+
+    describe('document layout (_layout in metadata)', () => {
+        it('extracts _layout from architecture metadata and exposes it as documentLayout', () => {
+            layoutServiceMock.getDefaultLayout.mockResolvedValue(null);
+            const archData = {
+                metadata: {
+                    _layout: {
+                        'node-a': { x: 10, y: 20, w: 100, h: 50 },
+                        'node-b': { x: 30, y: 40, w: 200, h: 80 },
+                    },
+                },
+            };
+            const { result } = renderHook(() => useDefaultLayout(namespace, '5', 'Architectures', archData));
+
+            expect(result.current.documentLayout).toEqual([
+                { id: 'node-a', position: { x: 10, y: 20 }, width: 100, height: 50 },
+                { id: 'node-b', position: { x: 30, y: 40 }, width: 200, height: 80 },
+            ]);
+        });
+
+        it('returns null documentLayout when metadata has no _layout', () => {
+            layoutServiceMock.getDefaultLayout.mockResolvedValue(null);
+            const archData = { metadata: { other: 'stuff' } };
+            const { result } = renderHook(() => useDefaultLayout(namespace, '5', 'Architectures', archData));
+
+            expect(result.current.documentLayout).toBeNull();
+        });
+
+        it('returns null documentLayout when no architectureData is passed', () => {
+            layoutServiceMock.getDefaultLayout.mockResolvedValue(null);
+            const { result } = renderHook(() => useDefaultLayout(namespace, '5', 'Architectures'));
+
+            expect(result.current.documentLayout).toBeNull();
+        });
+
+        it('uses document layout as defaultLayout when layoutSource is auto and _layout exists', async () => {
+            layoutServiceMock.getDefaultLayout.mockResolvedValue({
+                nodes: { 'node-a': { x: 999, y: 999 } },
+            });
+            const archData = {
+                metadata: {
+                    _layout: { 'node-a': { x: 10, y: 20, w: 100, h: 50 } },
+                },
+            };
+            const { result } = renderHook(() => useDefaultLayout(namespace, '5', 'Architectures', archData));
+
+            // Auto mode prefers document layout when available
+            expect(result.current.defaultLayout).toEqual([
+                { id: 'node-a', position: { x: 10, y: 20 }, width: 100, height: 50 },
+            ]);
+        });
+
+        it('reports hasBothSources when both _layout and server layout exist', async () => {
+            layoutServiceMock.getDefaultLayout.mockResolvedValue({
+                nodes: { 'node-a': { x: 999, y: 999 } },
+            });
+            const archData = {
+                metadata: {
+                    _layout: { 'node-a': { x: 10, y: 20 } },
+                },
+            };
+            const { result } = renderHook(() => useDefaultLayout(namespace, '5', 'Architectures', archData));
+
+            await waitFor(() => expect(result.current.hasBothSources).toBe(true));
+        });
+
+        it('switches to server layout when setLayoutSource is called with server', async () => {
+            layoutServiceMock.getDefaultLayout.mockResolvedValue({
+                nodes: { 'node-a': { x: 999, y: 888 } },
+            });
+            const archData = {
+                metadata: {
+                    _layout: { 'node-a': { x: 10, y: 20 } },
+                },
+            };
+            const { result } = renderHook(() => useDefaultLayout(namespace, '5', 'Architectures', archData));
+
+            await waitFor(() => expect(result.current.hasBothSources).toBe(true));
+
+            act(() => {
+                result.current.setLayoutSource('server');
+            });
+
+            await waitFor(() =>
+                expect(result.current.defaultLayout).toEqual([
+                    { id: 'node-a', position: { x: 999, y: 888 } },
+                ])
+            );
+        });
+    });
 });
diff --git a/calm-hub-ui/src/hub/hooks/useDefaultLayout.ts b/calm-hub-ui/src/hub/hooks/useDefaultLayout.ts
index 40525e1b7..97e9700ac 100644
--- a/calm-hub-ui/src/hub/hooks/useDefaultLayout.ts
+++ b/calm-hub-ui/src/hub/hooks/useDefaultLayout.ts
@@ -2,9 +2,11 @@ import { useCallback, useEffect, useMemo, useState } from 'react';
 import { CalmService } from '../../service/calm-service.js';
 import { LayoutService, LayoutResourceType } from '../../service/layout-service.js';
 import { isSlug } from '../../model/calm.js';
-import { CalmLayout, pinsToStoredPositions, storedPositionsToPins } from '../../model/layout.js';
+import { CalmLayout, apiResponseToStoredPositions, storedPositionsToLayoutMap, layoutMapToStoredPositions, type LayoutMap } from '../../model/layout.js';
 import { buildViewportKey, clearStoredNodePositions, StoredNodePosition } from '../../visualizer/services/node-position-service.js';
 
+export type LayoutSource = 'document' | 'server' | 'auto';
+
 export interface UseDefaultLayoutResult {
     /**
      * Namespace + calmType + resolved numeric id — the single key both the
@@ -40,6 +42,30 @@ export interface UseDefaultLayoutResult {
     saveError: string | null;
     save: (positions: StoredNodePosition[]) => Promise<void>;
     reset: () => void;
+    /** Layout extracted from the architecture document's metadata._layout, if present. */
+    documentLayout: StoredNodePosition[] | null;
+    /** Which layout source is currently active. */
+    layoutSource: LayoutSource;
+    /** Switch between document and server layout sources. */
+    setLayoutSource: (source: LayoutSource) => void;
+    /** Whether both document and server layouts are available (show the toggle). */
+    hasBothSources: boolean;
+}
+
+const LAYOUT_SOURCE_PREFIX = 'calm-hub:layout-source:';
+
+function loadPreferredSource(viewportKey: string | null | undefined): LayoutSource | null {
+    if (!viewportKey) return null;
+    try {
+        return localStorage.getItem(`${LAYOUT_SOURCE_PREFIX}${viewportKey}`) as LayoutSource | null;
+    } catch { return null; }
+}
+
+function savePreferredSource(viewportKey: string | null | undefined, source: LayoutSource): void {
+    if (!viewportKey) return;
+    try {
+        localStorage.setItem(`${LAYOUT_SOURCE_PREFIX}${viewportKey}`, source);
+    } catch { /* ignore */ }
 }
 
 const SUPPORTED_TYPES: Partial<Record<string, LayoutResourceType>> = {
@@ -52,8 +78,12 @@ const SUPPORTED_TYPES: Partial<Record<string, LayoutResourceType>> = {
  * pattern, and owns the save/reset actions. Returns an inert result (no
  * fetch, no key) for anything else — dropped files and any other calmType
  * are out of scope for server-side layouts.
+ *
+ * When `architectureData` includes `metadata._layout`, it is offered as a
+ * layout source alongside the server-side saved layout, with a user-selectable
+ * toggle when both are available.
  */
-export function useDefaultLayout(namespace: string, id: string, calmType: string): UseDefaultLayoutResult {
+export function useDefaultLayout(namespace: string, id: string, calmType: string, architectureData?: Record<string, unknown>): UseDefaultLayoutResult {
     const calmService = useMemo(() => new CalmService(), []);
     const layoutService = useMemo(() => new LayoutService(), []);
     const urlType = SUPPORTED_TYPES[calmType];
@@ -75,6 +105,16 @@ export function useDefaultLayout(namespace: string, id: string, calmType: string
     const [saving, setSaving] = useState(false);
     const [saveError, setSaveError] = useState<string | null>(null);
 
+    // Extract layout from architecture document metadata._layout if present.
+    const documentLayout = useMemo<StoredNodePosition[] | null>(() => {
+        if (!isSupportedType || !architectureData) return null;
+        const metadata = architectureData.metadata;
+        if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) return null;
+        const layoutData = (metadata as Record<string, unknown>)._layout;
+        if (!layoutData || typeof layoutData !== 'object' || Array.isArray(layoutData)) return null;
+        return layoutMapToStoredPositions(layoutData as LayoutMap);
+    }, [isSupportedType, architectureData]);
+
     // Resolve a slug id to its numeric id once per (namespace, id, calmType).
     useEffect(() => {
         if (!isSupportedType) {
@@ -120,6 +160,22 @@ export function useDefaultLayout(namespace: string, id: string, calmType: string
               ? null
               : undefined;
 
+    // Layout source selection — user can toggle between document and server layouts.
+    const [layoutSource, setLayoutSourceState] = useState<LayoutSource>('auto');
+
+    useEffect(() => {
+        const saved = loadPreferredSource(viewportKey);
+        if (saved) setLayoutSourceState(saved);
+        else setLayoutSourceState('auto');
+    }, [viewportKey]);
+
+    const setLayoutSource = useCallback((source: LayoutSource) => {
+        setLayoutSourceState(source);
+        savePreferredSource(viewportKey, source);
+        if (viewportKey) clearStoredNodePositions(viewportKey);
+        setLayoutEpoch((epoch) => epoch + 1);
+    }, [viewportKey]);
+
     // Fetch the server default once the id is settled (resolved to a number,
     // or resolution finished without a match).
     useEffect(() => {
@@ -144,7 +200,7 @@ export function useDefaultLayout(namespace: string, id: string, calmType: string
             .getDefaultLayout(namespace, resolvedId, urlType)
             .then((layout) => {
                 if (cancelled) return;
-                setDefaultLayout(layout ? pinsToStoredPositions(layout) : null);
+                setDefaultLayout(layout ? apiResponseToStoredPositions(layout as unknown as Record<string, unknown>) : null);
             })
             .catch(() => {
                 if (!cancelled) setDefaultLayout(null);
@@ -162,11 +218,13 @@ export function useDefaultLayout(namespace: string, id: string, calmType: string
             try {
                 const layout: CalmLayout = {
                     for: `/api/calm/namespaces/${namespace}/${urlType}/${resolvedId}`,
-                    pins: storedPositionsToPins(positions),
+                    nodes: storedPositionsToLayoutMap(positions),
                 };
                 await layoutService.saveDefaultLayout(namespace, resolvedId, layout, urlType);
                 if (viewportKey) clearStoredNodePositions(viewportKey);
                 setDefaultLayout(positions);
+                setLayoutSourceState('server');
+                savePreferredSource(viewportKey, 'server');
                 setLayoutEpoch((epoch) => epoch + 1);
             } catch (err) {
                 setSaveError(err instanceof Error ? err.message : 'Failed to save default layout');
@@ -186,20 +244,38 @@ export function useDefaultLayout(namespace: string, id: string, calmType: string
 
     const canSave = resolvedId !== undefined;
 
+    // The server-side layout fetched from the API.
+    const serverLayout = defaultLayout;
+
+    const hasBothSources = documentLayout != null && serverLayout != null;
+
+    // Resolve which layout to expose as `defaultLayout` based on user selection.
+    const effectiveDefaultLayout = useMemo<StoredNodePosition[] | null | undefined>(() => {
+        if (layoutSource === 'document' && documentLayout) return documentLayout;
+        if (layoutSource === 'server') return serverLayout ?? null;
+        // 'auto': prefer document if it exists, else server
+        if (documentLayout) return documentLayout;
+        return serverLayout;
+    }, [layoutSource, documentLayout, serverLayout]);
+
     // Memoised so consumers that key a useCallback/useMemo off the whole result
     // (e.g. DiagramSection's handleSaveLayout) get a stable reference instead of
     // a fresh object literal — and therefore a fresh dependency — every render.
     return useMemo(
         () => ({
             viewportKey,
-            defaultLayout,
+            defaultLayout: effectiveDefaultLayout,
             layoutEpoch,
             canSave,
             saving,
             saveError,
             save,
             reset,
+            documentLayout,
+            layoutSource,
+            setLayoutSource,
+            hasBothSources,
         }),
-        [viewportKey, defaultLayout, layoutEpoch, canSave, saving, saveError, save, reset]
+        [viewportKey, effectiveDefaultLayout, layoutEpoch, canSave, saving, saveError, save, reset, documentLayout, layoutSource, setLayoutSource, hasBothSources]
     );
 }
diff --git a/calm-hub-ui/src/model/layout.test.ts b/calm-hub-ui/src/model/layout.test.ts
new file mode 100644
index 000000000..ca6715f5e
--- /dev/null
+++ b/calm-hub-ui/src/model/layout.test.ts
@@ -0,0 +1,107 @@
+import { describe, it, expect } from 'vitest';
+import {
+    apiResponseToStoredPositions,
+    layoutMapToStoredPositions,
+    storedPositionsToLayoutMap,
+} from './layout.js';
+
+describe('layout model', () => {
+    describe('apiResponseToStoredPositions', () => {
+        it('parses the new nodes-map format with dimensions', () => {
+            const response = {
+                for: '/api/calm/namespaces/demo/architectures/1',
+                nodes: {
+                    'node-a': { x: 10, y: 20, w: 100, h: 50 },
+                    'node-b': { x: 30, y: 40, w: 200, h: 80 },
+                },
+            };
+            expect(apiResponseToStoredPositions(response)).toEqual([
+                { id: 'node-a', position: { x: 10, y: 20 }, width: 100, height: 50 },
+                { id: 'node-b', position: { x: 30, y: 40 }, width: 200, height: 80 },
+            ]);
+        });
+
+        it('parses the new nodes-map format without dimensions', () => {
+            const response = {
+                nodes: { 'node-a': { x: 5, y: 6 } },
+            };
+            expect(apiResponseToStoredPositions(response)).toEqual([
+                { id: 'node-a', position: { x: 5, y: 6 } },
+            ]);
+        });
+
+        it('parses the legacy pins array format', () => {
+            const response = {
+                pins: [
+                    { 'unique-id': 'node-a', position: { x: 10, y: 20 } },
+                    { 'unique-id': 'node-b', position: { x: 30, y: 40 } },
+                ],
+            };
+            expect(apiResponseToStoredPositions(response)).toEqual([
+                { id: 'node-a', position: { x: 10, y: 20 } },
+                { id: 'node-b', position: { x: 30, y: 40 } },
+            ]);
+        });
+
+        it('returns empty array when neither nodes nor pins exist', () => {
+            expect(apiResponseToStoredPositions({})).toEqual([]);
+        });
+
+        it('prefers nodes over pins when both exist', () => {
+            const response = {
+                nodes: { 'from-nodes': { x: 1, y: 2 } },
+                pins: [{ 'unique-id': 'from-pins', position: { x: 3, y: 4 } }],
+            };
+            const result = apiResponseToStoredPositions(response);
+            expect(result).toEqual([{ id: 'from-nodes', position: { x: 1, y: 2 } }]);
+        });
+    });
+
+    describe('layoutMapToStoredPositions', () => {
+        it('converts a LayoutMap to StoredNodePositions with dimensions', () => {
+            const map = {
+                'node-a': { x: 10, y: 20, w: 100, h: 50 },
+            };
+            expect(layoutMapToStoredPositions(map)).toEqual([
+                { id: 'node-a', position: { x: 10, y: 20 }, width: 100, height: 50 },
+            ]);
+        });
+
+        it('converts a LayoutMap without dimensions', () => {
+            const map = {
+                'node-a': { x: 10, y: 20 },
+            };
+            expect(layoutMapToStoredPositions(map)).toEqual([
+                { id: 'node-a', position: { x: 10, y: 20 } },
+            ]);
+        });
+    });
+
+    describe('storedPositionsToLayoutMap', () => {
+        it('converts positions with dimensions to a LayoutMap', () => {
+            const positions = [
+                { id: 'node-a', position: { x: 10.4, y: 20.7 }, width: 100.2, height: 50.9 },
+            ];
+            expect(storedPositionsToLayoutMap(positions)).toEqual({
+                'node-a': { x: 10, y: 21, w: 100, h: 51 },
+            });
+        });
+
+        it('converts positions without dimensions (omits w/h)', () => {
+            const positions = [
+                { id: 'node-a', position: { x: 10, y: 20 } },
+            ];
+            expect(storedPositionsToLayoutMap(positions)).toEqual({
+                'node-a': { x: 10, y: 20 },
+            });
+        });
+
+        it('rounds all values to integers', () => {
+            const positions = [
+                { id: 'n', position: { x: 1.1, y: 2.9 }, width: 100.5, height: 50.4 },
+            ];
+            const result = storedPositionsToLayoutMap(positions);
+            expect(result['n']).toEqual({ x: 1, y: 3, w: 101, h: 50 });
+        });
+    });
+});
diff --git a/calm-hub-ui/src/model/layout.ts b/calm-hub-ui/src/model/layout.ts
index 9497a7209..803c6a477 100644
--- a/calm-hub-ui/src/model/layout.ts
+++ b/calm-hub-ui/src/model/layout.ts
@@ -1,6 +1,12 @@
 import type { StoredNodePosition } from '../visualizer/services/node-position-service.js';
 
-/** A single node's saved position within a layout, keyed by its unique-id in the target document. */
+/** A single node's geometry within a layout — position and optional dimensions. */
+export interface LayoutEntry { x: number; y: number; w?: number; h?: number }
+
+/** Map keyed by node unique-id — the same shape the VS Code plugin persists in metadata._layout. */
+export type LayoutMap = Record<string, LayoutEntry>;
+
+/** Legacy pin format from the initial layout persistence (PR #2942). */
 export interface CalmLayoutPin {
     'unique-id': string;
     position: { x: number; y: number };
@@ -9,21 +15,51 @@ export interface CalmLayoutPin {
 /**
  * A layout as stored server-side: the shared, default arrangement for an architecture.
  * This is a CALM Hub-internal wire format — not a CALM community schema — and this
- * interface is its authoritative shape. Converted to/from the ReactFlow-facing
- * `StoredNodePosition[]` shape at the boundary, so `unique-id` never leaks into the
- * visualiser layer.
+ * interface is its authoritative shape. The `nodes` map matches the VS Code plugin's
+ * `metadata._layout` format for rendering parity.
  */
 export interface CalmLayout {
     for?: string;
     name?: string;
     description?: string;
-    pins: CalmLayoutPin[];
+    nodes: LayoutMap;
+}
+
+/** Convert an API response (new `nodes` map or legacy `pins` array) to StoredNodePositions. */
+export function apiResponseToStoredPositions(layout: Record<string, unknown>): StoredNodePosition[] {
+    if (layout.nodes && typeof layout.nodes === 'object' && !Array.isArray(layout.nodes)) {
+        const nodes = layout.nodes as LayoutMap;
+        return Object.entries(nodes).map(([id, entry]) => ({
+            id,
+            position: { x: entry.x, y: entry.y },
+            ...(entry.w != null && entry.h != null ? { width: entry.w, height: entry.h } : {}),
+        }));
+    }
+    if (Array.isArray((layout as { pins?: unknown }).pins)) {
+        const pins = (layout as { pins: CalmLayoutPin[] }).pins;
+        return pins.map((pin) => ({ id: pin['unique-id'], position: pin.position }));
+    }
+    return [];
 }
 
-export function pinsToStoredPositions(layout: CalmLayout): StoredNodePosition[] {
-    return layout.pins.map((pin) => ({ id: pin['unique-id'], position: pin.position }));
+/** Convert a LayoutMap (VS Code _layout format or new API format) to StoredNodePositions. */
+export function layoutMapToStoredPositions(layoutMap: LayoutMap): StoredNodePosition[] {
+    return Object.entries(layoutMap).map(([id, entry]) => ({
+        id,
+        position: { x: entry.x, y: entry.y },
+        ...(entry.w != null && entry.h != null ? { width: entry.w, height: entry.h } : {}),
+    }));
 }
 
-export function storedPositionsToPins(positions: StoredNodePosition[]): CalmLayoutPin[] {
-    return positions.map((position) => ({ 'unique-id': position.id, position: position.position }));
+/** Convert StoredNodePositions to the wire-format LayoutMap for saving. */
+export function storedPositionsToLayoutMap(positions: StoredNodePosition[]): LayoutMap {
+    const map: LayoutMap = {};
+    for (const p of positions) {
+        map[p.id] = {
+            x: Math.round(p.position.x),
+            y: Math.round(p.position.y),
+            ...(p.width != null && p.height != null ? { w: Math.round(p.width), h: Math.round(p.height) } : {}),
+        };
+    }
+    return map;
 }
diff --git a/calm-hub-ui/src/visualizer/components/reactflow/ArchitectureGraph.test.tsx b/calm-hub-ui/src/visualizer/components/reactflow/ArchitectureGraph.test.tsx
index 4d44eb581..24b26593c 100644
--- a/calm-hub-ui/src/visualizer/components/reactflow/ArchitectureGraph.test.tsx
+++ b/calm-hub-ui/src/visualizer/components/reactflow/ArchitectureGraph.test.tsx
@@ -4,7 +4,7 @@ import { useState, type ReactNode } from 'react';
 import type { Node } from 'reactflow';
 import { CalmArchitectureSchema } from '@finos/calm-models/types';
 import { ArchitectureGraph } from './ArchitectureGraph';
-import { saveNodePositions } from '../../services/node-position-service.js';
+import { saveNodePositions, clearStoredNodePositions } from '../../services/node-position-service.js';
 
 /**
  * Capture the props ReactFlow and MiniMap are rendered with, and render
@@ -248,7 +248,7 @@ describe('ArchitectureGraph', () => {
             return nodes?.find((n) => n.id === id)?.position;
         }
 
-        it('applies the local scratch layout, even when a different server default exists', () => {
+        it('applies local scratch over the default layout when both exist', () => {
             saveNodePositions(key, [{ id: 'node-1', position: { x: 111, y: 222 }, data: {} }] as Node[]);
 
             render(
@@ -295,22 +295,21 @@ describe('ArchitectureGraph', () => {
             expect(screen.getByTestId('react-flow')).toBeInTheDocument();
         });
 
-        it('re-applies positions when layoutEpoch changes, picking up a cleared scratch layout', () => {
+        it('falls back to scratch when no default layout is provided, then applies default on epoch bump after scratch is cleared', () => {
             saveNodePositions(key, [{ id: 'node-1', position: { x: 111, y: 222 }, data: {} }] as Node[]);
 
             const { rerender } = render(
                 <ArchitectureGraph
                     jsonData={mockCalmData}
                     viewportKey={key}
-                    defaultLayout={[{ id: 'node-1', position: { x: 333, y: 444 } }]}
+                    defaultLayout={null}
                     layoutEpoch={0}
                 />
             );
             expect(nodePosition('node-1')).toEqual({ x: 111, y: 222 });
 
-            // Simulate "reset to default": the scratch entry is cleared and the
-            // epoch bumps, forcing a clean re-apply of the server default.
-            localStorage.removeItem('calm-hub:node-positions:ns/id');
+            // Simulate save/reset: scratch is cleared before the epoch bumps.
+            clearStoredNodePositions(key);
             rerender(
                 <ArchitectureGraph
                     jsonData={mockCalmData}
diff --git a/calm-hub-ui/src/visualizer/components/reactflow/ArchitectureGraph.tsx b/calm-hub-ui/src/visualizer/components/reactflow/ArchitectureGraph.tsx
index 68a0a4766..c7467eded 100644
--- a/calm-hub-ui/src/visualizer/components/reactflow/ArchitectureGraph.tsx
+++ b/calm-hub-ui/src/visualizer/components/reactflow/ArchitectureGraph.tsx
@@ -173,9 +173,11 @@ export function ArchitectureGraph({
         const { nodes: parsedNodes, edges: parsedEdges } = parseCALMData(jsonData, onNodeClick);
         sourceNodesRef.current = parsedNodes;
 
-        // Precedence: an unsaved local drag always wins over the saved default —
-        // never silently discard a user's in-progress work — which in turn wins
-        // over the parsed auto-layout when neither is present.
+        // Precedence: a provided default layout (from document _layout or
+        // server-saved) wins over stale localStorage scratch, so the document's
+        // authoritative positions are always applied on page load. Scratch only
+        // applies when there is no default — i.e. a fresh architecture with
+        // neither a document _layout nor a server-saved layout.
         const localPositions = viewportKey ? loadStoredNodePositions(viewportKey) : null;
         const effectivePositions = localPositions ?? defaultLayout ?? null;
         const positionedNodes = applyPositions(parsedNodes, effectivePositions);
diff --git a/calm-hub-ui/src/visualizer/components/reactflow/PatternGraph.test.tsx b/calm-hub-ui/src/visualizer/components/reactflow/PatternGraph.test.tsx
index f504e3f11..dbf602ba2 100644
--- a/calm-hub-ui/src/visualizer/components/reactflow/PatternGraph.test.tsx
+++ b/calm-hub-ui/src/visualizer/components/reactflow/PatternGraph.test.tsx
@@ -3,7 +3,7 @@ import { render, screen } from '@testing-library/react';
 import { useState, type ReactNode } from 'react';
 import type { Node } from 'reactflow';
 import { PatternGraph } from './PatternGraph';
-import { saveNodePositions } from '../../services/node-position-service.js';
+import { saveNodePositions, clearStoredNodePositions } from '../../services/node-position-service.js';
 
 /**
  * Capture the props ReactFlow is rendered with. Mirrors ArchitectureGraph.test.tsx's
@@ -85,7 +85,7 @@ describe('PatternGraph', () => {
             return nodes?.find((n) => n.id === id)?.position;
         }
 
-        it('applies the local scratch layout, even when a different server default exists', () => {
+        it('applies local scratch over the default layout when both exist', () => {
             saveNodePositions(key, [{ id: 'node-1', position: { x: 111, y: 222 }, data: {} }] as Node[]);
 
             render(
@@ -132,22 +132,21 @@ describe('PatternGraph', () => {
             expect(screen.getByTestId('react-flow')).toBeInTheDocument();
         });
 
-        it('re-applies positions when layoutEpoch changes, picking up a cleared scratch layout', () => {
+        it('falls back to scratch when no default layout is provided, then applies default on epoch bump after scratch is cleared', () => {
             saveNodePositions(key, [{ id: 'node-1', position: { x: 111, y: 222 }, data: {} }] as Node[]);
 
             const { rerender } = render(
                 <PatternGraph
                     patternData={mockPatternData}
                     viewportKey={key}
-                    defaultLayout={[{ id: 'node-1', position: { x: 333, y: 444 } }]}
+                    defaultLayout={null}
                     layoutEpoch={0}
                 />
             );
             expect(nodePosition('node-1')).toEqual({ x: 111, y: 222 });
 
-            // Simulate "reset to default": the scratch entry is cleared and the
-            // epoch bumps, forcing a clean re-apply of the server default.
-            localStorage.removeItem('calm-hub:node-positions:ns/id');
+            // Simulate save/reset: scratch is cleared before the epoch bumps.
+            clearStoredNodePositions(key);
             rerender(
                 <PatternGraph
                     patternData={mockPatternData}
diff --git a/calm-hub-ui/src/visualizer/components/reactflow/PatternGraph.tsx b/calm-hub-ui/src/visualizer/components/reactflow/PatternGraph.tsx
index 9676981d8..821936878 100644
--- a/calm-hub-ui/src/visualizer/components/reactflow/PatternGraph.tsx
+++ b/calm-hub-ui/src/visualizer/components/reactflow/PatternGraph.tsx
@@ -124,8 +124,9 @@ export function PatternGraph({
         const { nodes: parsedNodes, edges: parsedEdges } = parsePatternData(patternData);
         sourceNodesRef.current = parsedNodes;
         sourceEdgesRef.current = parsedEdges;
-        // Precedence: an unsaved local drag always wins over the saved default,
-        // which in turn wins over the parsed auto-layout when neither is present.
+        // Precedence: a provided default layout (from document _layout or
+        // server-saved) wins over stale localStorage scratch. Scratch only
+        // applies when there is no default.
         const localPositions = viewportKey ? loadStoredNodePositions(viewportKey) : null;
         const effectivePositions = localPositions ?? defaultLayout ?? null;
         const positionedNodes = applyPositions(parsedNodes, effectivePositions);
diff --git a/calm-hub-ui/src/visualizer/services/node-position-service.test.tsx b/calm-hub-ui/src/visualizer/services/node-position-service.test.tsx
index 355ee7ae2..4ec5f068d 100644
--- a/calm-hub-ui/src/visualizer/services/node-position-service.test.tsx
+++ b/calm-hub-ui/src/visualizer/services/node-position-service.test.tsx
@@ -227,5 +227,61 @@ describe('node-position-service', () => {
             const viaDirectPositions = applyPositions(parsed, loadStoredNodePositions(key, storage));
             expect(viaStorage).toEqual(viaDirectPositions);
         });
+
+        it('applies width and height when present in positions', () => {
+            const parsed: Node[] = [
+                { id: 'node-1', position: { x: 0, y: 0 }, data: {} },
+            ];
+            const positions: StoredNodePosition[] = [
+                { id: 'node-1', position: { x: 50, y: 60 }, width: 200, height: 80 },
+            ];
+            const result = applyPositions(parsed, positions);
+            const node = result.find((n) => n.id === 'node-1')! as Node & { width?: number; height?: number };
+            expect(node.position).toEqual({ x: 50, y: 60 });
+            expect(node.width).toBe(200);
+            expect(node.height).toBe(80);
+            expect(node.style).toEqual({ width: 200, height: 80 });
+        });
+
+        it('skips reflow when all group nodes have explicit dimensions in positions', () => {
+            const parsed: Node[] = [
+                { id: 'group', type: 'group', position: { x: 0, y: 0 }, data: {} },
+                { id: 'child', position: { x: 0, y: 0 }, data: {}, parentId: 'group' } as Node,
+            ];
+            const positions: StoredNodePosition[] = [
+                { id: 'group', position: { x: 10, y: 10 }, width: 500, height: 400 },
+                { id: 'child', position: { x: 20, y: 20 }, width: 100, height: 50 },
+            ];
+            const result = applyPositions(parsed, positions);
+            const group = result.find((n) => n.id === 'group')! as Node & { width?: number; height?: number };
+            // With full dimensions, reflow is skipped — the group keeps its explicit size
+            expect(group.width).toBe(500);
+            expect(group.height).toBe(400);
+        });
+    });
+
+    describe('toStoredPositions with dimensions', () => {
+        it('captures width and height from node.width/height', () => {
+            const nodesWithDimensions: Node[] = [
+                { id: 'node-1', position: { x: 10, y: 20 }, data: {}, width: 150, height: 60 } as Node,
+            ];
+            const result = toStoredPositions(nodesWithDimensions);
+            expect(result[0]).toEqual({ id: 'node-1', position: { x: 10, y: 20 }, width: 150, height: 60 });
+        });
+
+        it('captures width and height from node.measured when node.width is absent', () => {
+            const nodesWithMeasured = [
+                { id: 'node-1', position: { x: 10, y: 20 }, data: {}, measured: { width: 180, height: 70 } },
+            ] as unknown as Node[];
+            const result = toStoredPositions(nodesWithMeasured);
+            expect(result[0]).toEqual({ id: 'node-1', position: { x: 10, y: 20 }, width: 180, height: 70 });
+        });
+
+        it('omits width/height when neither node.width nor measured is present', () => {
+            const result = toStoredPositions(nodes);
+            expect(result[0]).toEqual({ id: 'node-1', position: { x: 100, y: 200 } });
+            expect(result[0]).not.toHaveProperty('width');
+            expect(result[0]).not.toHaveProperty('height');
+        });
     });
 });
diff --git a/calm-hub-ui/src/visualizer/services/node-position-service.tsx b/calm-hub-ui/src/visualizer/services/node-position-service.tsx
index 77ac9e159..8c62858b0 100644
--- a/calm-hub-ui/src/visualizer/services/node-position-service.tsx
+++ b/calm-hub-ui/src/visualizer/services/node-position-service.tsx
@@ -4,6 +4,8 @@ import { reflowContainersToFitChildren } from '../components/reactflow/utils/lay
 export interface StoredNodePosition {
     id: string;
     position: { x: number; y: number };
+    width?: number;
+    height?: number;
 }
 
 /**
@@ -60,12 +62,18 @@ function legacyStorageKeyFor(key: string): string | undefined {
     return parts.length === VIEWPORT_KEY_SEGMENTS ? `${parts[0]}/${parts[2]}` : undefined;
 }
 
-/** Reduce a diagram's nodes to just the id/position pairs worth persisting. */
+/** Reduce a diagram's nodes to id, position, and measured dimensions worth persisting. */
 export function toStoredPositions(nodes: Node[]): StoredNodePosition[] {
-    return nodes.map((node) => ({
-        id: node.id,
-        position: { x: node.position.x, y: node.position.y },
-    }));
+    return nodes.map((node) => {
+        const n = node as Node & { width?: number; height?: number; measured?: { width?: number; height?: number } };
+        const w = n.width ?? n.measured?.width;
+        const h = n.height ?? n.measured?.height;
+        return {
+            id: node.id,
+            position: { x: node.position.x, y: node.position.y },
+            ...(w != null && h != null ? { width: w, height: h } : {}),
+        };
+    });
 }
 
 /** Persist the current positions of every node for the given diagram key. */
@@ -123,22 +131,42 @@ function parseStoredPositions(data: string): StoredNodePosition[] | null {
 }
 
 /**
- * Merge a set of positions onto freshly parsed nodes, matching by id, then
- * reflow containers so they re-hug their restored children. Returns the nodes
- * unchanged when there is nothing to apply, so callers fall back to the
- * auto-layout. Pure — shared by the localStorage scratch path
- * (`applyStoredPositions`) and by applying a server-saved default layout.
+ * Merge a set of positions (and optional dimensions) onto freshly parsed nodes,
+ * matching by id. When all container nodes have explicit width/height in the
+ * stored positions data, reflow is skipped — the layout is fully deterministic.
+ * Otherwise, containers are reflowed to fit their children (backward compat with
+ * position-only data). Returns the nodes unchanged when there is nothing to
+ * apply, so callers fall back to the auto-layout.
  */
 export function applyPositions(nodes: Node[], positions: StoredNodePosition[] | null): Node[] {
     if (!positions || positions.length === 0) return nodes;
 
-    const positionsById = new Map(positions.map((p) => [p.id, p.position]));
+    const positionsById = new Map(positions.map((p) => [p.id, p]));
     const merged = nodes.map((node) => {
-        const position = positionsById.get(node.id);
-        return position ? { ...node, position: { ...position } } : node;
+        const stored = positionsById.get(node.id);
+        if (!stored) return node;
+        const updated = { ...node, position: { ...stored.position } } as Node & { width?: number; height?: number };
+        if (stored.width != null && stored.height != null) {
+            updated.width = stored.width;
+            updated.height = stored.height;
+            updated.style = { ...updated.style, width: stored.width, height: stored.height };
+        }
+        return updated;
     });
 
-    return reflowContainersToFitChildren(merged);
+    // Only skip reflow when every container's dimensions came from the stored
+    // positions (not from the node's own pre-existing width/height). This ensures
+    // position-only restores (legacy data, localStorage scratch) still reflow.
+    const containerIds = new Set(
+        merged.filter((n) => n.parentId).map((n) => n.parentId!)
+    );
+    const allContainersDimensioned = containerIds.size === 0 ||
+        [...containerIds].every((id) => {
+            const stored = positionsById.get(id);
+            return stored?.width != null && stored?.height != null;
+        });
+
+    return allContainersDimensioned ? merged : reflowContainersToFitChildren(merged);
 }
 
 /**
diff --git a/calm-hub/nitrite/init-nitrite.sh b/calm-hub/nitrite/init-nitrite.sh
index 9f112c7b2..5f37cb2db 100755
--- a/calm-hub/nitrite/init-nitrite.sh
+++ b/calm-hub/nitrite/init-nitrite.sh
@@ -6091,6 +6091,53 @@ create_timeline_demo() {
     fi
 }
 
+create_layouts() {
+    print_status "Creating default layouts..."
+
+    # Seed a layout for the Conference Signup Architecture using the new nodes-map format.
+    # The architecture is created in create_architectures() under the "workshop" namespace;
+    # its id is resolved dynamically the same way version-seeding does.
+    local conf_arch_id
+    conf_arch_id=$(get_resource_id_by_name "workshop" "architectures" "Conference Signup Architecture")
+
+    if [[ -z "$conf_arch_id" ]]; then
+        print_warning "Could not resolve Conference Signup Architecture id; skipping layout seed"
+        return
+    fi
+
+    local layout_json
+    layout_json=$(cat <<'CALMDOC'
+{
+    "for": "/api/calm/namespaces/workshop/architectures/__ARCH_ID__",
+    "name": "Default",
+    "description": "Seeded demo layout for the Conference Signup Architecture",
+    "nodes": {
+        "conference-website":  { "x": 50,  "y": 30,  "w": 180, "h": 60 },
+        "load-balancer":       { "x": 300, "y": 30,  "w": 160, "h": 50 },
+        "attendees":           { "x": 300, "y": 150, "w": 160, "h": 60 },
+        "attendees-store":     { "x": 150, "y": 300, "w": 170, "h": 60 },
+        "attendees-cache":     { "x": 450, "y": 300, "w": 160, "h": 60 },
+        "k8s-cluster":         { "x": 100, "y": 100, "w": 560, "h": 300 }
+    }
+}
+CALMDOC
+)
+    # Replace the placeholder with the actual architecture id
+    layout_json="${layout_json//__ARCH_ID__/$conf_arch_id}"
+
+    local http_code
+    http_code=$(curl -s -o /dev/null -w "%{http_code}" -X PUT \
+        "$CALM_HUB_URL/api/calm/namespaces/workshop/architectures/$conf_arch_id/layout" \
+        -H "Content-Type: application/json" \
+        -d "$layout_json")
+
+    if [[ "$http_code" == "204" ]]; then
+        print_status "Created default layout for Conference Signup Architecture (id=$conf_arch_id)"
+    else
+        print_warning "Failed to create layout for Conference Signup Architecture (HTTP $http_code)"
+    fi
+}
+
 main() {
     print_status "Starting CalmHub NitriteDB initialization..."
     print_status "Target URL: $CALM_HUB_URL"
@@ -6106,6 +6153,7 @@ main() {
     create_patterns
     create_flows
     create_architectures
+    create_layouts
     create_user_access
     create_standards
     create_interfaces
diff --git a/calm-hub/src/integration-test/java/integration/NitriteEndToEndResource.java b/calm-hub/src/integration-test/java/integration/NitriteEndToEndResource.java
index 307a71684..7d11746f7 100644
--- a/calm-hub/src/integration-test/java/integration/NitriteEndToEndResource.java
+++ b/calm-hub/src/integration-test/java/integration/NitriteEndToEndResource.java
@@ -28,6 +28,7 @@ public Map<String, String> start() {
 
         return Map.of(
                 "calm.database.mode", "standalone",
+                "calm.standalone.seed-demo-data", "false",
                 "calm.standalone.data-directory", tempDir.toString(),
                 "calm.standalone.database-name", "testdb",
                 "calm.standalone.username", "admin",
diff --git a/calm-hub/src/main/java/org/finos/calm/config/StandaloneDemoSeeder.java b/calm-hub/src/main/java/org/finos/calm/config/StandaloneDemoSeeder.java
new file mode 100644
index 000000000..868345c33
--- /dev/null
+++ b/calm-hub/src/main/java/org/finos/calm/config/StandaloneDemoSeeder.java
@@ -0,0 +1,193 @@
+package org.finos.calm.config;
+
+import io.quarkus.arc.lookup.LookupIfProperty;
+import io.quarkus.runtime.StartupEvent;
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.enterprise.event.Observes;
+import jakarta.inject.Inject;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.finos.calm.domain.Architecture;
+import org.finos.calm.domain.exception.NamespaceNotFoundException;
+import org.finos.calm.store.ArchitectureStore;
+import org.finos.calm.store.LayoutStore;
+import org.finos.calm.store.NamespaceStore;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * Seeds a demo namespace, architecture, and layout on first startup in standalone mode,
+ * so the Hub has something to render immediately without running init-nitrite.sh.
+ * Only runs when the database is empty (no namespaces exist yet).
+ */
+@LookupIfProperty(name = "calm.database.mode", stringValue = "standalone")
+@ApplicationScoped
+public class StandaloneDemoSeeder {
+
+    private static final Logger LOG = LoggerFactory.getLogger(StandaloneDemoSeeder.class);
+
+    @Inject
+    NamespaceStore namespaceStore;
+
+    @Inject
+    ArchitectureStore architectureStore;
+
+    @Inject
+    LayoutStore layoutStore;
+
+    @ConfigProperty(name = "calm.database.mode", defaultValue = "mongo")
+    String databaseMode;
+
+    @ConfigProperty(name = "calm.standalone.seed-demo-data", defaultValue = "false")
+    boolean seedDemoEnabled;
+
+    void onStart(@Observes StartupEvent ev) {
+        if (!"standalone".equals(databaseMode)) {
+            return;
+        }
+
+        if (!seedDemoEnabled) {
+            LOG.info("Demo data seeding disabled (calm.standalone.seed-demo-data=false) — skipping demo seed");
+            return;
+        }
+
+        try {
+            if (!namespaceStore.getNamespaces().isEmpty()) {
+                LOG.info("Database already has data — skipping demo seed");
+                return;
+            }
+        } catch (Exception e) {
+            LOG.warn("Could not check existing namespaces — skipping demo seed", e);
+            return;
+        }
+
+        LOG.info("Empty database detected — seeding demo data with layout");
+        seedDemoData();
+    }
+
+    private void seedDemoData() {
+        try {
+            namespaceStore.createNamespace("demo", "Demo namespace with a seeded layout");
+
+            String architectureJson = """
+                {
+                    "nodes": [
+                        {
+                            "unique-id": "web-app",
+                            "node-type": "service",
+                            "name": "Web Application",
+                            "description": "Frontend web application serving user requests"
+                        },
+                        {
+                            "unique-id": "api-gateway",
+                            "node-type": "service",
+                            "name": "API Gateway",
+                            "description": "Routes and authenticates API requests"
+                        },
+                        {
+                            "unique-id": "user-service",
+                            "node-type": "service",
+                            "name": "User Service",
+                            "description": "Manages user accounts and authentication"
+                        },
+                        {
+                            "unique-id": "order-service",
+                            "node-type": "service",
+                            "name": "Order Service",
+                            "description": "Processes and manages orders"
+                        },
+                        {
+                            "unique-id": "database",
+                            "node-type": "database",
+                            "name": "PostgreSQL",
+                            "description": "Primary relational data store"
+                        },
+                        {
+                            "unique-id": "message-queue",
+                            "node-type": "service",
+                            "name": "Message Queue",
+                            "description": "Async event bus for inter-service communication"
+                        }
+                    ],
+                    "relationships": [
+                        {
+                            "unique-id": "web-to-gateway",
+                            "relationship-type": { "connects": { "source": { "node": "web-app" }, "destination": { "node": "api-gateway" } } },
+                            "protocol": "HTTPS"
+                        },
+                        {
+                            "unique-id": "gateway-to-user",
+                            "relationship-type": { "connects": { "source": { "node": "api-gateway" }, "destination": { "node": "user-service" } } },
+                            "protocol": "HTTPS"
+                        },
+                        {
+                            "unique-id": "gateway-to-order",
+                            "relationship-type": { "connects": { "source": { "node": "api-gateway" }, "destination": { "node": "order-service" } } },
+                            "protocol": "HTTPS"
+                        },
+                        {
+                            "unique-id": "user-to-db",
+                            "relationship-type": { "connects": { "source": { "node": "user-service" }, "destination": { "node": "database" } } },
+                            "protocol": "JDBC"
+                        },
+                        {
+                            "unique-id": "order-to-db",
+                            "relationship-type": { "connects": { "source": { "node": "order-service" }, "destination": { "node": "database" } } },
+                            "protocol": "JDBC"
+                        },
+                        {
+                            "unique-id": "order-to-queue",
+                            "relationship-type": { "connects": { "source": { "node": "order-service" }, "destination": { "node": "message-queue" } } },
+                            "protocol": "AMQP"
+                        }
+                    ],
+                    "metadata": {
+                        "_layout": {
+                            "web-app":       { "x": 350, "y": 30,  "w": 200, "h": 60 },
+                            "api-gateway":   { "x": 350, "y": 150, "w": 180, "h": 55 },
+                            "user-service":  { "x": 150, "y": 300, "w": 180, "h": 55 },
+                            "order-service": { "x": 550, "y": 300, "w": 180, "h": 55 },
+                            "database":      { "x": 350, "y": 450, "w": 170, "h": 60 },
+                            "message-queue": { "x": 700, "y": 450, "w": 180, "h": 55 }
+                        }
+                    }
+                }
+                """;
+
+            Architecture architecture = new Architecture.ArchitectureBuilder()
+                    .setNamespace("demo")
+                    .setName("Microservices Demo")
+                    .setDescription("A demo microservices architecture with a pre-seeded layout")
+                    .setVersion("1.0.0")
+                    .setArchitecture(architectureJson)
+                    .build();
+
+            Architecture created = architectureStore.createArchitectureForNamespace(architecture);
+            int archId = created.getId();
+            LOG.info("Seeded demo architecture (id={})", archId);
+
+            String layoutJson = """
+                {
+                    "for": "/api/calm/namespaces/demo/architectures/%d",
+                    "name": "Default",
+                    "description": "Pre-seeded layout demonstrating width/height persistence",
+                    "nodes": {
+                        "web-app":       { "x": 350, "y": 30,  "w": 200, "h": 60 },
+                        "api-gateway":   { "x": 350, "y": 150, "w": 180, "h": 55 },
+                        "user-service":  { "x": 150, "y": 300, "w": 180, "h": 55 },
+                        "order-service": { "x": 550, "y": 300, "w": 180, "h": 55 },
+                        "database":      { "x": 350, "y": 450, "w": 170, "h": 60 },
+                        "message-queue": { "x": 700, "y": 450, "w": 180, "h": 55 }
+                    }
+                }
+                """.formatted(archId);
+
+            layoutStore.upsertLayout("demo", archId, layoutJson);
+            LOG.info("Seeded default layout for demo architecture");
+
+        } catch (NamespaceNotFoundException e) {
+            LOG.error("Failed to seed demo data — namespace not found after creation", e);
+        } catch (Exception e) {
+            LOG.error("Failed to seed demo data", e);
+        }
+    }
+}
diff --git a/calm-hub/src/main/java/org/finos/calm/migration/steps/MongoLayoutFormatMigrationStep.java b/calm-hub/src/main/java/org/finos/calm/migration/steps/MongoLayoutFormatMigrationStep.java
new file mode 100644
index 000000000..a1297c825
--- /dev/null
+++ b/calm-hub/src/main/java/org/finos/calm/migration/steps/MongoLayoutFormatMigrationStep.java
@@ -0,0 +1,108 @@
+package org.finos.calm.migration.steps;
+
+import com.mongodb.client.MongoCollection;
+import com.mongodb.client.MongoDatabase;
+import io.quarkus.arc.lookup.LookupIfProperty;
+import jakarta.enterprise.context.ApplicationScoped;
+import org.bson.Document;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.finos.calm.migration.SchemaMigrationStep;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.List;
+
+/**
+ * Migrates layout documents from the legacy {@code pins} array format to the new {@code nodes}
+ * map format, which aligns with the VS Code plugin's {@code metadata._layout} shape and includes
+ * width/height for deterministic rendering.
+ *
+ * <h2>Legacy format (pins)</h2>
+ * <pre>{@code
+ * { "for": "...", "pins": [{ "unique-id": "node-a", "position": { "x": 0, "y": 0 } }] }
+ * }</pre>
+ *
+ * <h2>New format (nodes)</h2>
+ * <pre>{@code
+ * { "for": "...", "nodes": { "node-a": { "x": 0, "y": 0 } } }
+ * }</pre>
+ *
+ * <p>Idempotent: documents that already have a {@code nodes} map (or no {@code pins} field) are
+ * skipped. Positions without width/height are migrated as-is — the frontend handles missing
+ * dimensions gracefully by falling back to reflow.</p>
+ */
+@LookupIfProperty(name = "calm.database.mode", stringValue = "mongo", lookupIfMissing = true)
+@ApplicationScoped
+public class MongoLayoutFormatMigrationStep implements SchemaMigrationStep {
+
+    private static final Logger LOG = LoggerFactory.getLogger(MongoLayoutFormatMigrationStep.class);
+    private static final String COLLECTION = "layouts";
+    private static final String LAYOUT_FIELD = "layout";
+
+    private final MongoDatabase database;
+
+    @ConfigProperty(name = "calm.database.mode", defaultValue = "mongo")
+    String databaseMode;
+
+    public MongoLayoutFormatMigrationStep(MongoDatabase database) {
+        this.database = database;
+    }
+
+    @Override
+    public int fromVersion() {
+        return 14;
+    }
+
+    @Override
+    public void apply() {
+        if (!"mongo".equals(databaseMode)) {
+            LOG.info("Skipping layout format migration (database mode: {})", databaseMode);
+            return;
+        }
+        migrateLayouts();
+    }
+
+    public void migrateLayouts() {
+        MongoCollection<Document> layouts = database.getCollection(COLLECTION);
+        int migrated = 0;
+        int skipped = 0;
+
+        for (Document doc : layouts.find()) {
+            Document layoutDoc = doc.get(LAYOUT_FIELD, Document.class);
+            if (layoutDoc == null) {
+                skipped++;
+                continue;
+            }
+
+            if (layoutDoc.containsKey("nodes")) {
+                skipped++;
+                continue;
+            }
+
+            List<Document> pins = layoutDoc.getList("pins", Document.class);
+            if (pins == null) {
+                skipped++;
+                continue;
+            }
+
+            Document nodesMap = new Document();
+            for (Document pin : pins) {
+                String uniqueId = pin.getString("unique-id");
+                if (uniqueId == null) continue;
+                Document position = pin.get("position", Document.class);
+                if (position == null) continue;
+
+                Document entry = new Document("x", position.get("x")).append("y", position.get("y"));
+                nodesMap.append(uniqueId, entry);
+            }
+
+            layoutDoc.remove("pins");
+            layoutDoc.append("nodes", nodesMap);
+
+            layouts.replaceOne(new Document("_id", doc.getObjectId("_id")), doc);
+            migrated++;
+        }
+
+        LOG.info("Layout format migration complete: {} migrated, {} skipped", migrated, skipped);
+    }
+}
diff --git a/calm-hub/src/main/java/org/finos/calm/migration/steps/NitriteLayoutFormatMigrationStep.java b/calm-hub/src/main/java/org/finos/calm/migration/steps/NitriteLayoutFormatMigrationStep.java
new file mode 100644
index 000000000..6939bd9ab
--- /dev/null
+++ b/calm-hub/src/main/java/org/finos/calm/migration/steps/NitriteLayoutFormatMigrationStep.java
@@ -0,0 +1,111 @@
+package org.finos.calm.migration.steps;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.quarkus.arc.lookup.LookupIfProperty;
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+import org.dizitart.no2.Nitrite;
+import org.dizitart.no2.collection.Document;
+import org.dizitart.no2.collection.NitriteCollection;
+import org.finos.calm.config.StandaloneQualifier;
+import org.finos.calm.migration.SchemaMigrationStep;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * NitriteDB counterpart to {@link MongoLayoutFormatMigrationStep}: migrates layout documents
+ * from the legacy {@code pins} array format to the new {@code nodes} map format.
+ *
+ * <p>Both steps declare {@code fromVersion() == 14} but never coexist — each is gated by
+ * {@code @LookupIfProperty} on a different value of {@code calm.database.mode}, so exactly
+ * one is a CDI bean in any given deployment.</p>
+ *
+ * <p>In Nitrite the {@code layout} field is a raw JSON string (unlike Mongo's parsed Document),
+ * so the migration parses the string, transforms it, and writes it back.</p>
+ */
+@LookupIfProperty(name = "calm.database.mode", stringValue = "standalone")
+@ApplicationScoped
+public class NitriteLayoutFormatMigrationStep implements SchemaMigrationStep {
+
+    private static final Logger LOG = LoggerFactory.getLogger(NitriteLayoutFormatMigrationStep.class);
+    private static final String COLLECTION_NAME = "layouts";
+    private static final String LAYOUT_FIELD = "layout";
+    private static final ObjectMapper MAPPER = new ObjectMapper();
+
+    private final NitriteCollection layoutCollection;
+
+    @Inject
+    public NitriteLayoutFormatMigrationStep(@StandaloneQualifier Nitrite db) {
+        this.layoutCollection = db.getCollection(COLLECTION_NAME);
+    }
+
+    @Override
+    public int fromVersion() {
+        return 14;
+    }
+
+    @Override
+    public void apply() {
+        migrateLayouts();
+    }
+
+    void migrateLayouts() {
+        int migrated = 0;
+        int skipped = 0;
+
+        for (Document doc : layoutCollection.find()) {
+            String layoutJson = doc.get(LAYOUT_FIELD, String.class);
+            if (layoutJson == null) {
+                skipped++;
+                continue;
+            }
+
+            try {
+                Map<String, Object> layout = MAPPER.readValue(layoutJson, new TypeReference<>() {});
+
+                if (layout.containsKey("nodes")) {
+                    skipped++;
+                    continue;
+                }
+
+                Object pinsObj = layout.get("pins");
+                if (!(pinsObj instanceof List<?> pins)) {
+                    skipped++;
+                    continue;
+                }
+
+                Map<String, Object> nodesMap = new LinkedHashMap<>();
+                for (Object pinObj : pins) {
+                    if (!(pinObj instanceof Map<?, ?> pin)) continue;
+                    Object uniqueId = pin.get("unique-id");
+                    if (!(uniqueId instanceof String id)) continue;
+                    Object position = pin.get("position");
+                    if (!(position instanceof Map<?, ?> pos)) continue;
+
+                    Map<String, Object> entry = new LinkedHashMap<>();
+                    entry.put("x", pos.get("x"));
+                    entry.put("y", pos.get("y"));
+                    nodesMap.put(id, entry);
+                }
+
+                layout.remove("pins");
+                layout.put("nodes", nodesMap);
+
+                doc.put(LAYOUT_FIELD, MAPPER.writeValueAsString(layout));
+                layoutCollection.update(doc);
+                migrated++;
+            } catch (JsonProcessingException e) {
+                LOG.warn("Skipping layout document with unparseable JSON: {}", e.getMessage());
+                skipped++;
+            }
+        }
+
+        LOG.info("Nitrite layout format migration complete: {} migrated, {} skipped", migrated, skipped);
+    }
+}
diff --git a/calm-hub/src/main/resources/application.properties b/calm-hub/src/main/resources/application.properties
index 7d9c2cf27..bb30515be 100644
--- a/calm-hub/src/main/resources/application.properties
+++ b/calm-hub/src/main/resources/application.properties
@@ -11,6 +11,9 @@ calm.standalone.database-name=calmSchemas
 calm.standalone.username=admin
 calm.standalone.password=admin
 calm.standalone.init-script-path=mongo/init-mongo.js
+# Seed a demo namespace/architecture/layout on first startup when the database is empty.
+# Set to false to start standalone mode with a completely empty database.
+calm.standalone.seed-demo-data=false
 # Read-only mode: when true, opens Nitrite with readOnly(true) and rejects mutating HTTP verbs
 calm.readonly=false
 
diff --git a/calm-hub/src/test/java/org/finos/calm/migration/steps/TestMongoLayoutFormatMigrationStepShould.java b/calm-hub/src/test/java/org/finos/calm/migration/steps/TestMongoLayoutFormatMigrationStepShould.java
new file mode 100644
index 000000000..5b5fba741
--- /dev/null
+++ b/calm-hub/src/test/java/org/finos/calm/migration/steps/TestMongoLayoutFormatMigrationStepShould.java
@@ -0,0 +1,165 @@
+package org.finos.calm.migration.steps;
+
+import com.mongodb.client.FindIterable;
+import com.mongodb.client.MongoCollection;
+import com.mongodb.client.MongoCursor;
+import com.mongodb.client.MongoDatabase;
+import org.bson.Document;
+import org.bson.conversions.Bson;
+import org.bson.types.ObjectId;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.ArgumentCaptor;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.mockito.junit.jupiter.MockitoSettings;
+import org.mockito.quality.Strictness;
+
+import java.util.Iterator;
+import java.util.List;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.contains;
+import static org.hamcrest.Matchers.is;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.verifyNoInteractions;
+import static org.mockito.Mockito.when;
+
+@ExtendWith(MockitoExtension.class)
+@MockitoSettings(strictness = Strictness.LENIENT)
+class TestMongoLayoutFormatMigrationStepShould {
+
+    private interface DocumentMongoCollection extends MongoCollection<Document> {
+    }
+
+    private interface DocumentFindIterable extends FindIterable<Document> {
+    }
+
+    private interface DocumentMongoCursor extends MongoCursor<Document> {
+    }
+
+    private MongoDatabase database;
+    private MongoCollection<Document> layouts;
+    private MongoLayoutFormatMigrationStep step;
+
+    @BeforeEach
+    void setup() {
+        database = mock(MongoDatabase.class);
+        layouts = mock(DocumentMongoCollection.class);
+        when(database.getCollection("layouts")).thenReturn(layouts);
+
+        step = new MongoLayoutFormatMigrationStep(database);
+        step.databaseMode = "mongo";
+        stubLayouts(List.of());
+    }
+
+    /** Backs {@code layouts.find()} with a fresh cursor over the given documents on each call. */
+    private void stubLayouts(List<Document> documents) {
+        when(layouts.find()).thenAnswer(invocation -> {
+            Iterator<Document> iterator = documents.iterator();
+            MongoCursor<Document> cursor = mock(DocumentMongoCursor.class);
+            when(cursor.hasNext()).thenAnswer(hasNext -> iterator.hasNext());
+            when(cursor.next()).thenAnswer(next -> iterator.next());
+
+            FindIterable<Document> iterable = mock(DocumentFindIterable.class);
+            when(iterable.iterator()).thenReturn(cursor);
+            return iterable;
+        });
+    }
+
+    private static Document layoutRecord(Document layout) {
+        return new Document("_id", new ObjectId()).append("layout", layout);
+    }
+
+    /** A legacy pin; a {@code null} uniqueId omits the id and null coordinates omit the position. */
+    private static Document pin(String uniqueId, Integer x, Integer y) {
+        Document pin = new Document();
+        if (uniqueId != null) {
+            pin.append("unique-id", uniqueId);
+        }
+        if (x != null || y != null) {
+            pin.append("position", new Document("x", x).append("y", y));
+        }
+        return pin;
+    }
+
+    @Test
+    void run_at_schema_version_fourteen() {
+        assertThat(step.fromVersion(), is(14));
+    }
+
+    @Test
+    void skip_the_whole_step_when_not_running_against_mongo() {
+        step.databaseMode = "standalone";
+
+        step.apply();
+
+        verifyNoInteractions(database);
+    }
+
+    @Test
+    void convert_a_legacy_pins_layout_into_the_nodes_map() {
+        Document layout = new Document("for", "arch")
+                .append("pins", List.of(pin("node-a", 10, 20)));
+        stubLayouts(List.of(layoutRecord(layout)));
+
+        step.apply();
+
+        ArgumentCaptor<Document> replacement = ArgumentCaptor.forClass(Document.class);
+        verify(layouts).replaceOne(any(Bson.class), replacement.capture());
+
+        Document savedLayout = replacement.getValue().get("layout", Document.class);
+        assertThat(savedLayout.containsKey("pins"), is(false));
+        Document nodes = savedLayout.get("nodes", Document.class);
+        assertThat(nodes.get("node-a"), is(new Document("x", 10).append("y", 20)));
+    }
+
+    @Test
+    void ignore_pins_that_are_missing_a_unique_id_or_a_position() {
+        Document layout = new Document("for", "arch").append("pins", List.of(
+                pin("node-a", 10, 20),
+                pin(null, 30, 40),
+                pin("node-c", null, null)));
+        stubLayouts(List.of(layoutRecord(layout)));
+
+        step.apply();
+
+        ArgumentCaptor<Document> replacement = ArgumentCaptor.forClass(Document.class);
+        verify(layouts).replaceOne(any(Bson.class), replacement.capture());
+
+        Document nodes = replacement.getValue().get("layout", Document.class).get("nodes", Document.class);
+        assertThat(nodes.keySet(), contains("node-a"));
+    }
+
+    @Test
+    void skip_a_record_that_has_no_layout_field() {
+        stubLayouts(List.of(new Document("_id", new ObjectId())));
+
+        step.apply();
+
+        verify(layouts, never()).replaceOne(any(Bson.class), any(Document.class));
+    }
+
+    @Test
+    void skip_a_layout_that_is_already_in_the_nodes_format() {
+        Document layout = new Document("for", "arch")
+                .append("nodes", new Document("node-a", new Document("x", 1).append("y", 2)));
+        stubLayouts(List.of(layoutRecord(layout)));
+
+        step.apply();
+
+        verify(layouts, never()).replaceOne(any(Bson.class), any(Document.class));
+    }
+
+    @Test
+    void skip_a_layout_that_has_neither_pins_nor_nodes() {
+        stubLayouts(List.of(layoutRecord(new Document("for", "arch"))));
+
+        step.apply();
+
+        verify(layouts, never()).replaceOne(any(Bson.class), any(Document.class));
+    }
+}
diff --git a/calm-hub/src/test/java/org/finos/calm/migration/steps/TestNitriteLayoutFormatMigrationStepShould.java b/calm-hub/src/test/java/org/finos/calm/migration/steps/TestNitriteLayoutFormatMigrationStepShould.java
new file mode 100644
index 000000000..4e2d7814a
--- /dev/null
+++ b/calm-hub/src/test/java/org/finos/calm/migration/steps/TestNitriteLayoutFormatMigrationStepShould.java
@@ -0,0 +1,137 @@
+package org.finos.calm.migration.steps;
+
+import org.dizitart.no2.Nitrite;
+import org.dizitart.no2.collection.Document;
+import org.dizitart.no2.collection.DocumentCursor;
+import org.dizitart.no2.collection.NitriteCollection;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.ArgumentCaptor;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.mockito.junit.jupiter.MockitoSettings;
+import org.mockito.quality.Strictness;
+
+import java.util.List;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.is;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+@ExtendWith(MockitoExtension.class)
+@MockitoSettings(strictness = Strictness.LENIENT)
+class TestNitriteLayoutFormatMigrationStepShould {
+
+    private NitriteCollection layoutCollection;
+    private NitriteLayoutFormatMigrationStep step;
+
+    @BeforeEach
+    void setup() {
+        Nitrite db = mock(Nitrite.class);
+        layoutCollection = mock(NitriteCollection.class);
+        when(db.getCollection("layouts")).thenReturn(layoutCollection);
+
+        step = new NitriteLayoutFormatMigrationStep(db);
+        stubLayouts(List.of());
+    }
+
+    private void stubLayouts(List<Document> documents) {
+        DocumentCursor cursor = mock(DocumentCursor.class);
+        when(layoutCollection.find()).thenReturn(cursor);
+        when(cursor.iterator()).thenAnswer(invocation -> documents.iterator());
+    }
+
+    private static Document layoutDoc(String layoutJson) {
+        return Document.createDocument()
+                .put("namespace", "finos")
+                .put("architectureId", 1)
+                .put("layout", layoutJson);
+    }
+
+    @Test
+    void run_at_schema_version_fourteen() {
+        assertThat(step.fromVersion(), is(14));
+    }
+
+    @Test
+    void convert_a_legacy_pins_layout_into_the_nodes_map() {
+        String legacyJson = """
+                {"for":"arch","pins":[{"unique-id":"node-a","position":{"x":10,"y":20}}]}""";
+        stubLayouts(List.of(layoutDoc(legacyJson)));
+
+        step.apply();
+
+        ArgumentCaptor<Document> captor = ArgumentCaptor.forClass(Document.class);
+        verify(layoutCollection).update(captor.capture());
+
+        String updatedJson = captor.getValue().get("layout", String.class);
+        assertThat(updatedJson.contains("\"nodes\""), is(true));
+        assertThat(updatedJson.contains("\"pins\""), is(false));
+        assertThat(updatedJson.contains("\"node-a\""), is(true));
+    }
+
+    @Test
+    void ignore_pins_that_are_missing_a_unique_id_or_a_position() {
+        String legacyJson = """
+                {"for":"arch","pins":[{"unique-id":"node-a","position":{"x":10,"y":20}},{"position":{"x":30,"y":40}},{"unique-id":"node-c"}]}""";
+        stubLayouts(List.of(layoutDoc(legacyJson)));
+
+        step.apply();
+
+        ArgumentCaptor<Document> captor = ArgumentCaptor.forClass(Document.class);
+        verify(layoutCollection).update(captor.capture());
+
+        String updatedJson = captor.getValue().get("layout", String.class);
+        assertThat(updatedJson.contains("\"node-a\""), is(true));
+        assertThat(updatedJson.contains("\"node-c\""), is(false));
+    }
+
+    @Test
+    void skip_a_record_that_has_no_layout_field() {
+        Document doc = Document.createDocument().put("namespace", "finos").put("architectureId", 1);
+        stubLayouts(List.of(doc));
+
+        step.apply();
+
+        verify(layoutCollection, never()).update(any(Document.class));
+    }
+
+    @Test
+    void skip_a_layout_that_is_already_in_the_nodes_format() {
+        String nodesJson = """
+                {"for":"arch","nodes":{"node-a":{"x":1,"y":2}}}""";
+        stubLayouts(List.of(layoutDoc(nodesJson)));
+
+        step.apply();
+
+        verify(layoutCollection, never()).update(any(Document.class));
+    }
+
+    @Test
+    void skip_a_layout_that_has_neither_pins_nor_nodes() {
+        String json = """
+                {"for":"arch"}""";
+        stubLayouts(List.of(layoutDoc(json)));
+
+        step.apply();
+
+        verify(layoutCollection, never()).update(any(Document.class));
+    }
+
+    @Test
+    void skip_a_layout_with_unparseable_json() {
+        Document doc = Document.createDocument()
+                .put("namespace", "finos")
+                .put("architectureId", 1)
+                .put("layout", "{not valid json");
+        stubLayouts(List.of(doc));
+
+        step.apply();
+
+        verify(layoutCollection, never()).update(any(Document.class));
+    }
+}