@auto-engineer/narrative 1.139.0 → 1.140.0

package/src/{getNarratives.specs.ts → getScenes.specs.ts}

@@ -3,15 +3,15 @@ import { fileURLToPath } from 'node:url';
 import { InMemoryFileStore } from '@auto-engineer/file-store';
 import { NodeFileStore } from '@auto-engineer/file-store/node';
 import { beforeEach, describe, expect, it } from 'vitest';
-import { clearGetNarrativesCache, getNarratives } from './getNarratives';
-import { type Example, type Model, modelToNarrative, type Narrative, type QuerySlice } from './index';
+import { clearGetScenesCache, getScenes } from './getScenes';
+import { type Example, type Model, modelToNarrative, type QueryMoment, type Scene } from './index';
 import { modelSchema } from './schema';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const pattern = /\.(narrative)\.(ts)$/;
 
-describe('getNarratives', (_mode) => {
+describe('getScenes', (_mode) => {
   let vfs: NodeFileStore;
   let root: string;
 
@@ -19,8 +19,8 @@ describe('getNarratives', (_mode) => {
     vfs = new NodeFileStore();
     root = path.resolve(__dirname);
   });
-  it('loads multiple narratives and generates correct models', async () => {
-    const flows = await getNarratives({ vfs, root: path.resolve(__dirname), pattern, fastFsScan: true });
+  it('loads multiple scenes and generates correct models', async () => {
+    const flows = await getScenes({ vfs, root: path.resolve(__dirname), pattern, fastFsScan: true });
     const schemas = flows.toModel();
 
     const parseResult = modelSchema.safeParse(schemas);
@@ -30,11 +30,11 @@ describe('getNarratives', (_mode) => {
     expect(parseResult.success).toBe(true);
 
     expect(schemas).toHaveProperty('variant', 'specs');
-    expect(schemas).toHaveProperty('narratives');
+    expect(schemas).toHaveProperty('scenes');
     expect(schemas).toHaveProperty('messages');
     expect(schemas).toHaveProperty('integrations');
 
-    const flowsArray = schemas.narratives;
+    const flowsArray = schemas.scenes;
     expect(Array.isArray(flowsArray)).toBe(true);
     expect(flowsArray.length).toBeGreaterThanOrEqual(2);
 
@@ -48,24 +48,24 @@ describe('getNarratives', (_mode) => {
     expect(placeOrder).toBeDefined();
 
     if (items) {
-      expect(items.slices).toHaveLength(2);
-      const createItemSlice = items.slices[0];
-      expect(createItemSlice.type).toBe('command');
-      expect(createItemSlice.name).toBe('Create item');
-      expect(createItemSlice.stream).toBe('item-${id}');
-      if (createItemSlice.type === 'command') {
-        expect(createItemSlice.client.specs).toBeDefined();
-        expect(Array.isArray(createItemSlice.client.specs)).toBe(true);
-        expect(createItemSlice.client.specs).toHaveLength(1);
-        expect(createItemSlice.client.specs[0].type).toBe('describe');
-        expect(createItemSlice.client.specs[0].title).toBe('A form that allows users to add items');
-        if (createItemSlice.client.specs[0].type === 'describe') {
-          expect(createItemSlice.client.specs[0].children).toHaveLength(1);
+      expect(items.moments).toHaveLength(2);
+      const createItemMoment = items.moments[0];
+      expect(createItemMoment.type).toBe('command');
+      expect(createItemMoment.name).toBe('Create item');
+      expect(createItemMoment.stream).toBe('item-${id}');
+      if (createItemMoment.type === 'command') {
+        expect(createItemMoment.client.specs).toBeDefined();
+        expect(Array.isArray(createItemMoment.client.specs)).toBe(true);
+        expect(createItemMoment.client.specs).toHaveLength(1);
+        expect(createItemMoment.client.specs[0].type).toBe('describe');
+        expect(createItemMoment.client.specs[0].title).toBe('A form that allows users to add items');
+        if (createItemMoment.client.specs[0].type === 'describe') {
+          expect(createItemMoment.client.specs[0].children).toHaveLength(1);
         }
-        expect(createItemSlice.server.specs).toBeDefined();
-        expect(Array.isArray(createItemSlice.server.specs)).toBe(true);
-        expect(createItemSlice.server.specs).toHaveLength(1);
-        const spec = createItemSlice.server.specs[0];
+        expect(createItemMoment.server.specs).toBeDefined();
+        expect(Array.isArray(createItemMoment.server.specs)).toBe(true);
+        expect(createItemMoment.server.specs).toHaveLength(1);
+        const spec = createItemMoment.server.specs[0];
         expect(spec.feature).toBeDefined();
         expect(spec.rules).toHaveLength(1);
         const rule = spec.rules[0];
@@ -95,55 +95,55 @@ describe('getNarratives', (_mode) => {
         }
       }
 
-      const viewItemSlice = items.slices[1] as QuerySlice;
-      expect(viewItemSlice.type).toBe('query');
-      expect(viewItemSlice.name).toBe('view items');
-      expect(viewItemSlice.client.specs).toBeDefined();
-      expect(Array.isArray(viewItemSlice.client.specs)).toBe(true);
-      expect(viewItemSlice.client.specs).toHaveLength(1);
-      expect(viewItemSlice.client.specs[0].type).toBe('describe');
-      expect(viewItemSlice.client.specs[0].title).toBe('view Items Screen');
-      if (viewItemSlice.client.specs[0].type === 'describe') {
-        expect(viewItemSlice.client.specs[0].children).toHaveLength(3);
+      const viewItemMoment = items.moments[1] as QueryMoment;
+      expect(viewItemMoment.type).toBe('query');
+      expect(viewItemMoment.name).toBe('view items');
+      expect(viewItemMoment.client.specs).toBeDefined();
+      expect(Array.isArray(viewItemMoment.client.specs)).toBe(true);
+      expect(viewItemMoment.client.specs).toHaveLength(1);
+      expect(viewItemMoment.client.specs[0].type).toBe('describe');
+      expect(viewItemMoment.client.specs[0].title).toBe('view Items Screen');
+      if (viewItemMoment.client.specs[0].type === 'describe') {
+        expect(viewItemMoment.client.specs[0].children).toHaveLength(3);
       }
-      expect(viewItemSlice.request).toBeDefined();
-      expect(viewItemSlice.request).toMatch(
+      expect(viewItemMoment.request).toBeDefined();
+      expect(viewItemMoment.request).toMatch(
         /query items\(\$itemId: String!\) {\s+items\(itemId: \$itemId\) {\s+id\s+description\s+}/,
       );
 
-      const data = viewItemSlice?.server?.data;
+      const data = viewItemMoment?.server?.data;
       if (!data || !Array.isArray(data.items)) throw new Error('No data found in view items slice');
 
       expect(data.items).toHaveLength(1);
       expect(data.items[0].target).toMatchObject({ type: 'State', name: 'items' });
       expect(data.items[0].origin).toMatchObject({ name: 'ItemsProjection', type: 'projection' });
 
-      const specs = viewItemSlice?.server?.specs;
+      const specs = viewItemMoment?.server?.specs;
       if (specs == null || specs.length === 0 || specs[0].feature === '')
         throw new Error('No specs found in view items slice');
       expect(specs).toBeDefined();
     }
 
     if (placeOrder) {
-      expect(placeOrder.slices).toHaveLength(1);
-      const submitOrderSlice = placeOrder.slices[0];
-      expect(submitOrderSlice.type).toBe('command');
-      expect(submitOrderSlice.name).toBe('Submit order');
-      expect(submitOrderSlice.stream).toBe('order-${orderId}');
-
-      if (submitOrderSlice.type === 'command') {
-        expect(submitOrderSlice.client.specs).toBeDefined();
-        expect(Array.isArray(submitOrderSlice.client.specs)).toBe(true);
-        expect(submitOrderSlice.client.specs).toHaveLength(1);
-        expect(submitOrderSlice.client.specs[0].type).toBe('describe');
-        expect(submitOrderSlice.client.specs[0].title).toBe('Order submission form');
-        if (submitOrderSlice.client.specs[0].type === 'describe') {
-          expect(submitOrderSlice.client.specs[0].children).toHaveLength(2);
+      expect(placeOrder.moments).toHaveLength(1);
+      const submitOrderMoment = placeOrder.moments[0];
+      expect(submitOrderMoment.type).toBe('command');
+      expect(submitOrderMoment.name).toBe('Submit order');
+      expect(submitOrderMoment.stream).toBe('order-${orderId}');
+
+      if (submitOrderMoment.type === 'command') {
+        expect(submitOrderMoment.client.specs).toBeDefined();
+        expect(Array.isArray(submitOrderMoment.client.specs)).toBe(true);
+        expect(submitOrderMoment.client.specs).toHaveLength(1);
+        expect(submitOrderMoment.client.specs[0].type).toBe('describe');
+        expect(submitOrderMoment.client.specs[0].title).toBe('Order submission form');
+        if (submitOrderMoment.client.specs[0].type === 'describe') {
+          expect(submitOrderMoment.client.specs[0].children).toHaveLength(2);
         }
-        expect(submitOrderSlice.server.specs).toBeDefined();
-        expect(Array.isArray(submitOrderSlice.server.specs)).toBe(true);
-        expect(submitOrderSlice.server.specs).toHaveLength(1);
-        const spec = submitOrderSlice.server.specs[0];
+        expect(submitOrderMoment.server.specs).toBeDefined();
+        expect(Array.isArray(submitOrderMoment.server.specs)).toBe(true);
+        expect(submitOrderMoment.server.specs).toHaveLength(1);
+        const spec = submitOrderMoment.server.specs[0];
         expect(spec.rules).toHaveLength(1);
         const rule = spec.rules[0];
         expect(rule.examples).toHaveLength(1);
@@ -206,21 +206,21 @@ describe('getNarratives', (_mode) => {
   });
 
   it('validates the complete schema with Zod', async () => {
-    const flows = await getNarratives({ vfs: vfs, root, pattern: /\.(narrative)\.(ts)$/, fastFsScan: true });
+    const flows = await getScenes({ vfs: vfs, root, pattern: /\.(narrative)\.(ts)$/, fastFsScan: true });
     const schemas = flows.toModel();
     const parsed = modelSchema.parse(schemas);
     expect(parsed.variant).toBe('specs');
-    expect(Array.isArray(parsed.narratives)).toBe(true);
+    expect(Array.isArray(parsed.scenes)).toBe(true);
     expect(Array.isArray(parsed.messages)).toBe(true);
     expect(Array.isArray(parsed.integrations)).toBe(true);
   });
 
-  it('should handle narratives with integrations', async () => {
-    const flows = await getNarratives({ vfs: vfs, root: root, pattern: /\.(narrative)\.(ts)$/, fastFsScan: true });
+  it('should handle scenes with integrations', async () => {
+    const flows = await getScenes({ vfs: vfs, root: root, pattern: /\.(narrative)\.(ts)$/, fastFsScan: true });
     const specsSchema = flows.toModel();
 
-    const flowsWithIntegrations = specsSchema.narratives.filter((f) =>
-      f.slices.some((s) => {
+    const flowsWithIntegrations = specsSchema.scenes.filter((f) =>
+      f.moments.some((s) => {
         if (s.type === 'command' || s.type === 'query') {
           return (
             s.server.data?.items?.some(
@@ -240,11 +240,11 @@ describe('getNarratives', (_mode) => {
   });
 
   it('should handle react slices correctly', async () => {
-    const flows = await getNarratives({ vfs: vfs, root: root, pattern: /\.(narrative)\.(ts)$/, fastFsScan: true });
+    const flows = await getScenes({ vfs: vfs, root: root, pattern: /\.(narrative)\.(ts)$/, fastFsScan: true });
     const specsSchema = flows.toModel();
 
-    const reactSlices = specsSchema.narratives.flatMap((f) => f.slices.filter((s) => s.type === 'react'));
-    reactSlices.forEach((slice) => {
+    const reactMoments = specsSchema.scenes.flatMap((f) => f.moments.filter((s) => s.type === 'react'));
+    reactMoments.forEach((slice) => {
       if (slice.type === 'react') {
         expect(slice.server).toBeDefined();
         expect(slice.server.specs).toBeDefined();
@@ -264,7 +264,7 @@ describe('getNarratives', (_mode) => {
   });
 
   it('should parse and validate a complete flow with all slice types', async () => {
-    const flows = await getNarratives({ vfs: vfs, root: root, pattern: /\.(narrative)\.(ts)$/, fastFsScan: true });
+    const flows = await getScenes({ vfs: vfs, root: root, pattern: /\.(narrative)\.(ts)$/, fastFsScan: true });
     const schemas = flows.toModel();
 
     const validationResult = modelSchema.safeParse(schemas);
@@ -275,8 +275,8 @@ describe('getNarratives', (_mode) => {
 
     const validatedData = validationResult.data!;
     expect(
-      validatedData.narratives.every((flow) =>
-        flow.slices.every((slice) => {
+      validatedData.scenes.every((flow) =>
+        flow.moments.every((slice) => {
           if (slice.type === 'command' || slice.type === 'query') {
             return slice.client !== undefined && slice.server !== undefined;
           } else if (slice.type === 'react') {
@@ -290,94 +290,96 @@ describe('getNarratives', (_mode) => {
     ).toBe(true);
   });
 
-  it('should have ids for narratives and slices that have ids', async () => {
-    const flows = await getNarratives({ vfs: vfs, root: root, pattern: /\.(narrative)\.(ts)$/, fastFsScan: true });
+  it('should have ids for scenes and slices that have ids', async () => {
+    const flows = await getScenes({ vfs: vfs, root: root, pattern: /\.(narrative)\.(ts)$/, fastFsScan: true });
 
     const schemas = flows.toModel();
 
-    const testFlowWithIds = schemas.narratives.find((f) => f.name === 'Test Flow with IDs');
+    const testFlowWithIds = schemas.scenes.find((f) => f.name === 'Test Flow with IDs');
     if (!testFlowWithIds) return;
-    const commandSlice = testFlowWithIds.slices.find((s) => s.name === 'Create test item');
-    expect(commandSlice?.id).toBe('SLICE-001');
-    expect(commandSlice?.type).toBe('command');
-    const querySlice = testFlowWithIds.slices.find((s) => s.name === 'Get test items');
-    expect(querySlice?.id).toBe('SLICE-002');
-    expect(querySlice?.type).toBe('query');
-    const reactSlice = testFlowWithIds.slices.find((s) => s.name === 'React to test event');
-    expect(reactSlice?.id).toBe('SLICE-003');
-    expect(reactSlice?.type).toBe('react');
+    const commandMoment = testFlowWithIds.moments.find((s) => s.name === 'Create test item');
+    expect(commandMoment?.id).toBe('SLICE-001');
+    expect(commandMoment?.type).toBe('command');
+    const queryMoment = testFlowWithIds.moments.find((s) => s.name === 'Get test items');
+    expect(queryMoment?.id).toBe('SLICE-002');
+    expect(queryMoment?.type).toBe('query');
+    const reactMoment = testFlowWithIds.moments.find((s) => s.name === 'React to test event');
+    expect(reactMoment?.id).toBe('SLICE-003');
+    expect(reactMoment?.type).toBe('react');
   });
 
   it('should have ids for command slice rules', async () => {
-    const flows = await getNarratives({ vfs: vfs, root: root, pattern: /\.(narrative)\.(ts)$/, fastFsScan: true });
+    const flows = await getScenes({ vfs: vfs, root: root, pattern: /\.(narrative)\.(ts)$/, fastFsScan: true });
     const schemas = flows.toModel();
 
-    const testFlowWithIds = schemas.narratives.find((f) => f.name === 'Test Flow with IDs');
+    const testFlowWithIds = schemas.scenes.find((f) => f.name === 'Test Flow with IDs');
     if (!testFlowWithIds) return;
 
-    const commandSlice = testFlowWithIds.slices.find((s) => s.name === 'Create test item');
-    if (commandSlice?.type !== 'command') return;
+    const commandMoment = testFlowWithIds.moments.find((s) => s.name === 'Create test item');
+    if (commandMoment?.type !== 'command') return;
 
-    expect(commandSlice.server.specs[0].rules).toHaveLength(2);
+    expect(commandMoment.server.specs[0].rules).toHaveLength(2);
 
-    const rule1 = commandSlice.server.specs[0].rules.find(
+    const rule1 = commandMoment.server.specs[0].rules.find(
       (r) => r.name === 'Valid test items should be created successfully',
     );
     expect(rule1?.id).toBe('RULE-001');
 
-    const rule2 = commandSlice.server.specs[0].rules.find((r) => r.name === 'Invalid test items should be rejected');
+    const rule2 = commandMoment.server.specs[0].rules.find((r) => r.name === 'Invalid test items should be rejected');
     expect(rule2?.id).toBe('RULE-002');
   });
 
   it('should have ids for query slice rules', async () => {
-    const flows = await getNarratives({ vfs: vfs, root: root, pattern: /\.(narrative)\.(ts)$/, fastFsScan: true });
+    const flows = await getScenes({ vfs: vfs, root: root, pattern: /\.(narrative)\.(ts)$/, fastFsScan: true });
     const schemas = flows.toModel();
 
-    const testFlowWithIds = schemas.narratives.find((f) => f.name === 'Test Flow with IDs');
+    const testFlowWithIds = schemas.scenes.find((f) => f.name === 'Test Flow with IDs');
     if (!testFlowWithIds) return;
 
-    const querySlice = testFlowWithIds.slices.find((s) => s.name === 'Get test items');
-    if (querySlice?.type !== 'query') return;
+    const queryMoment = testFlowWithIds.moments.find((s) => s.name === 'Get test items');
+    if (queryMoment?.type !== 'query') return;
 
-    expect(querySlice.server.specs[0].rules).toHaveLength(1);
+    expect(queryMoment.server.specs[0].rules).toHaveLength(1);
 
-    const rule3 = querySlice.server.specs[0].rules.find((r) => r.name === 'Items should be retrievable after creation');
+    const rule3 = queryMoment.server.specs[0].rules.find(
+      (r) => r.name === 'Items should be retrievable after creation',
+    );
     expect(rule3?.id).toBe('RULE-003');
   });
 
   it('should have ids for react slice rules', async () => {
-    const flows = await getNarratives({ vfs: vfs, root: root, pattern: /\.(narrative)\.(ts)$/, fastFsScan: true });
+    const flows = await getScenes({ vfs: vfs, root: root, pattern: /\.(narrative)\.(ts)$/, fastFsScan: true });
     const schemas = flows.toModel();
 
-    const testFlowWithIds = schemas.narratives.find((f) => f.name === 'Test Flow with IDs');
+    const testFlowWithIds = schemas.scenes.find((f) => f.name === 'Test Flow with IDs');
     if (!testFlowWithIds) return;
 
-    const reactSlice = testFlowWithIds.slices.find((s) => s.name === 'React to test event');
-    if (reactSlice?.type !== 'react') return;
+    const reactMoment = testFlowWithIds.moments.find((s) => s.name === 'React to test event');
+    if (reactMoment?.type !== 'react') return;
 
-    expect(reactSlice.server.specs[0].rules).toHaveLength(1);
+    expect(reactMoment.server.specs[0].rules).toHaveLength(1);
 
-    const rule4 = reactSlice.server.specs[0].rules.find((r) => r.name === 'System should react to test item creation');
+    const rule4 = reactMoment.server.specs[0].rules.find((r) => r.name === 'System should react to test item creation');
     expect(rule4?.id).toBe('RULE-004');
   });
 
   it('should handle when examples correctly', async () => {
-    const flows = await getNarratives({
+    const flows = await getScenes({
       vfs,
       root,
       pattern: /(?:^|\/)questionnaires\.narrative\.(?:ts|tsx|js|jsx|mjs|cjs)$/,
     });
     const model = flows.toModel();
 
-    const questionnaireFlow = model.narratives.find((f) => f.name === 'Questionnaires');
+    const questionnaireFlow = model.scenes.find((f) => f.name === 'Questionnaires');
     expect(questionnaireFlow).toBeDefined();
 
     if (questionnaireFlow) {
-      const submitSlice = questionnaireFlow.slices.find((s) => s.name === 'submits the questionnaire');
-      expect(submitSlice?.type).toBe('command');
+      const submitMoment = questionnaireFlow.moments.find((s) => s.name === 'submits the questionnaire');
+      expect(submitMoment?.type).toBe('command');
 
-      if (submitSlice?.type === 'command') {
-        const example = submitSlice.server?.specs?.[0]?.rules[0]?.examples[0];
+      if (submitMoment?.type === 'command') {
+        const example = submitMoment.server?.specs?.[0]?.rules[0]?.examples[0];
         const whenStep = example?.steps?.find((s) => s.keyword === 'When');
         if (whenStep && 'text' in whenStep) {
           expect(whenStep.text).toBe('SubmitQuestionnaire');
@@ -387,7 +389,7 @@ describe('getNarratives', (_mode) => {
   });
 
   it('should correctly assign commandRef correctly', async () => {
-    const flows = await getNarratives({
+    const flows = await getScenes({
       vfs,
       root,
       pattern: /(?:^|\/)questionnaires\.narrative\.(?:ts|tsx|js|jsx|mjs|cjs)$/,
@@ -400,9 +402,9 @@ describe('getNarratives', (_mode) => {
   it('should handle experience slice with client specs', async () => {
     const memoryVfs = new InMemoryFileStore();
     const flowWithExperienceContent = `
-import { flow, experience, it, specs } from '@auto-engineer/narrative';
+import { scene, experience, it, specs } from '@auto-engineer/narrative';
 
-flow('Test Experience Flow', () => {
+scene('Test Experience Flow', () => {
   experience('Homepage', 'H1a4Bn6Cy').client(() => {
     specs(() => {
       it('show a hero section with a welcome message');
@@ -414,26 +416,26 @@ flow('Test Experience Flow', () => {
 
     await memoryVfs.write('/test/experience.narrative.ts', new TextEncoder().encode(flowWithExperienceContent));
 
-    const flows = await getNarratives({ vfs: memoryVfs, root: '/test', pattern, fastFsScan: true });
+    const flows = await getScenes({ vfs: memoryVfs, root: '/test', pattern, fastFsScan: true });
     const model = flows.toModel();
 
-    const experienceFlow = model.narratives.find((f) => f.name === 'Test Experience Flow');
+    const experienceFlow = model.scenes.find((f) => f.name === 'Test Experience Flow');
     expect(experienceFlow).toBeDefined();
 
     if (experienceFlow) {
-      const homepageSlice = experienceFlow.slices.find((s) => s.name === 'Homepage');
-      expect(homepageSlice).toBeDefined();
-      expect(homepageSlice?.type).toBe('experience');
-
-      if (homepageSlice?.type === 'experience') {
-        expect(homepageSlice.client).toBeDefined();
-        expect(homepageSlice.client.specs).toBeDefined();
-        expect(Array.isArray(homepageSlice.client.specs)).toBe(true);
-        expect(homepageSlice.client.specs).toHaveLength(2);
-        expect(homepageSlice.client.specs[0].type).toBe('it');
-        expect(homepageSlice.client.specs[0].title).toBe('show a hero section with a welcome message');
-        expect(homepageSlice.client.specs[1].type).toBe('it');
-        expect(homepageSlice.client.specs[1].title).toBe('allow user to start the questionnaire');
+      const homepageMoment = experienceFlow.moments.find((s) => s.name === 'Homepage');
+      expect(homepageMoment).toBeDefined();
+      expect(homepageMoment?.type).toBe('experience');
+
+      if (homepageMoment?.type === 'experience') {
+        expect(homepageMoment.client).toBeDefined();
+        expect(homepageMoment.client.specs).toBeDefined();
+        expect(Array.isArray(homepageMoment.client.specs)).toBe(true);
+        expect(homepageMoment.client.specs).toHaveLength(2);
+        expect(homepageMoment.client.specs[0].type).toBe('it');
+        expect(homepageMoment.client.specs[0].title).toBe('show a hero section with a welcome message');
+        expect(homepageMoment.client.specs[1].type).toBe('it');
+        expect(homepageMoment.client.specs[1].title).toBe('allow user to start the questionnaire');
       }
     }
   });
@@ -441,9 +443,9 @@ flow('Test Experience Flow', () => {
   it('simulates browser execution with transpiled CommonJS code', async () => {
     const memoryVfs = new InMemoryFileStore();
     const flowContent = `
-import { flow, experience, it, specs } from '@auto-engineer/narrative';
+import { scene, experience, it, specs } from '@auto-engineer/narrative';
 
-flow('Browser Test Flow', () => {
+scene('Browser Test Flow', () => {
   experience('HomePage').client(() => {
     specs(() => {
       it('render correctly');
@@ -461,12 +463,12 @@ flow('Browser Test Flow', () => {
 
     await executeAST(['/browser/test.narrative.ts'], memoryVfs, {}, '/browser');
 
-    const flows = registry.getAllNarratives();
+    const flows = registry.getAllScenes();
     expect(flows).toHaveLength(1);
     expect(flows[0].name).toBe('Browser Test Flow');
-    expect(flows[0].slices).toHaveLength(1);
+    expect(flows[0].moments).toHaveLength(1);
 
-    const slice = flows[0].slices[0];
+    const slice = flows[0].moments[0];
     expect(slice.type).toBe('experience');
     expect(slice.name).toBe('HomePage');
 
@@ -487,9 +489,9 @@ flow('Browser Test Flow', () => {
     const { registry } = await import('./narrative-registry');
 
     const flowContent = `
-import { flow, experience } from '@auto-engineer/narrative';
+import { scene, experience } from '@auto-engineer/narrative';
 
-flow('Questionnaires', 'Q9m2Kp4Lx', () => {
+scene('Questionnaires', 'Q9m2Kp4Lx', () => {
   experience('Homepage', 'H1a4Bn6Cy').client(() => {});
 });
       `;
@@ -502,12 +504,12 @@ flow('Questionnaires', 'Q9m2Kp4Lx', () => {
       executeAST(['/browser/questionnaires.narrative.ts'], memoryVfs, {}, '/browser'),
     ).resolves.toBeDefined();
 
-    const flows = registry.getAllNarratives();
+    const flows = registry.getAllScenes();
     expect(flows).toHaveLength(1);
     expect(flows[0].name).toBe('Questionnaires');
-    expect(flows[0].slices).toHaveLength(1);
+    expect(flows[0].moments).toHaveLength(1);
 
-    const slice = flows[0].slices[0];
+    const slice = flows[0].moments[0];
     expect(slice.type).toBe('experience');
     expect(slice.name).toBe('Homepage');
   });
@@ -515,7 +517,7 @@ flow('Questionnaires', 'Q9m2Kp4Lx', () => {
   it('should handle flow type resolutions correctly', async () => {
     const memoryVfs = new InMemoryFileStore();
     const questionnaireFlowContent = `
-import { data, flow, should, specs, rule, example } from '../narrative';
+import { data, scene, should, specs, rule, example } from '../narrative';
 import { command, query } from '../fluent-builder';
 import gql from 'graphql-tag';
 import { source } from '../data-narrative-builders';
@@ -562,7 +564,7 @@ type QuestionnaireProgress = State<
   }
 >;
 
-flow('questionnaires-test', () => {
+scene('questionnaires-test', () => {
   query('views progress')
     .server(() => {
       specs('Questionnaire progress display', () => {
@@ -612,9 +614,9 @@ flow('questionnaires-test', () => {
 
     await memoryVfs.write('/test/questionnaires.narrative.ts', new TextEncoder().encode(questionnaireFlowContent));
 
-    const flows = await getNarratives({ vfs: memoryVfs, root: '/test', pattern, fastFsScan: true });
+    const flows = await getScenes({ vfs: memoryVfs, root: '/test', pattern, fastFsScan: true });
     const model = flows.toModel();
-    const testFlow = model.narratives.find((f) => f.name === 'questionnaires-test');
+    const testFlow = model.scenes.find((f) => f.name === 'questionnaires-test');
     expect(testFlow).toBeDefined();
     if (testFlow !== null && testFlow !== undefined) {
       validateSubmitQuestionnaireCommand(testFlow);
@@ -625,21 +627,21 @@ flow('questionnaires-test', () => {
   });
 
   it('correctly distinguishes between State and Event types in given clauses with empty when', async () => {
-    const flows = await getNarratives({ vfs, root, pattern, fastFsScan: true });
+    const flows = await getScenes({ vfs, root, pattern, fastFsScan: true });
     const model = flows.toModel();
 
-    const mixedGivenFlow = model.narratives.find((f) => f.name === 'Mixed Given Types');
+    const mixedGivenFlow = model.scenes.find((f) => f.name === 'Mixed Given Types');
     expect(mixedGivenFlow).toBeDefined();
 
     if (!mixedGivenFlow) return;
 
-    const querySlice = mixedGivenFlow.slices.find((s) => s.name === 'system status check');
-    expect(querySlice).toBeDefined();
-    expect(querySlice?.type).toBe('query');
+    const queryMoment = mixedGivenFlow.moments.find((s) => s.name === 'system status check');
+    expect(queryMoment).toBeDefined();
+    expect(queryMoment?.type).toBe('query');
 
-    if (querySlice?.type !== 'query') return;
+    if (queryMoment?.type !== 'query') return;
 
-    const example = querySlice.server.specs[0].rules[0]?.examples[0];
+    const example = queryMoment.server.specs[0].rules[0]?.examples[0];
     expect(example).toBeDefined();
 
     if (example !== null && example !== undefined) {
@@ -651,7 +653,7 @@ flow('questionnaires-test', () => {
   });
 
   it('does not emit empty generics or empty when clauses', async () => {
-    const flows = await getNarratives({
+    const flows = await getScenes({
       vfs,
       root,
       pattern: /(?:^|\/)questionnaires\.narrative\.(?:ts|tsx|js|jsx|mjs|cjs)$/,
@@ -668,7 +670,7 @@ flow('questionnaires-test', () => {
   });
 
   it('should not generate phantom messages with empty names', async () => {
-    const flows = await getNarratives({
+    const flows = await getScenes({
       vfs,
       root: root,
       pattern: /(?:^|\/)questionnaires\.narrative\.(?:ts|tsx|js|jsx|mjs|cjs)$/,
@@ -691,7 +693,7 @@ flow('questionnaires-test', () => {
   it('should convert all given events to eventRef', async (): Promise<void> => {
     const memoryVfs = new InMemoryFileStore();
     const todoSummaryFlowContent = `
-import { flow, query, specs, rule, example, type Event, type State } from '@auto-engineer/narrative';
+import { scene, query, specs, rule, example, type Event, type State } from '@auto-engineer/narrative';
 
 type TodoAdded = Event<
   'TodoAdded',
@@ -731,7 +733,7 @@ type TodoListSummary = State<
   }
 >;
 
-flow('Todo List', () => {
+scene('Todo List', () => {
   query('views completion summary')
     .server(() => {
       specs(() => {
@@ -780,20 +782,20 @@ flow('Todo List', () => {
 
     await memoryVfs.write('/test/todo-summary.narrative.ts', new TextEncoder().encode(todoSummaryFlowContent));
 
-    const flows = await getNarratives({ vfs: memoryVfs, root: '/test', pattern, fastFsScan: true });
+    const flows = await getScenes({ vfs: memoryVfs, root: '/test', pattern, fastFsScan: true });
     const model = flows.toModel();
 
-    const todoFlow = model.narratives.find((f) => f.name === 'Todo List');
+    const todoFlow = model.scenes.find((f) => f.name === 'Todo List');
     expect(todoFlow).toBeDefined();
 
     if (!todoFlow) return;
 
-    const summarySlice = todoFlow.slices.find((s) => s.name === 'views completion summary');
-    expect(summarySlice?.type).toBe('query');
+    const summaryMoment = todoFlow.moments.find((s) => s.name === 'views completion summary');
+    expect(summaryMoment?.type).toBe('query');
 
-    if (summarySlice?.type !== 'query') return;
+    if (summaryMoment?.type !== 'query') return;
 
-    const example = summarySlice.server.specs[0].rules[0]?.examples[0];
+    const example = summaryMoment.server.specs[0].rules[0]?.examples[0];
     expect(example).toBeDefined();
     expect(example.steps).toBeDefined();
     expect(Array.isArray(example.steps)).toBe(true);
@@ -849,11 +851,11 @@ function validateTodoMessages(model: Model): void {
   expect(todoListSummaryState?.type).toBe('state');
 }
 
-function validateSubmitQuestionnaireCommand(questionnaireFlow: Narrative): void {
-  const submitSlice = questionnaireFlow.slices.find((s) => s.name === 'submits questionnaire');
-  expect(submitSlice?.type).toBe('command');
-  if (submitSlice?.type === 'command') {
-    const example = submitSlice.server?.specs?.[0]?.rules[0]?.examples[0];
+function validateSubmitQuestionnaireCommand(questionnaireFlow: Scene): void {
+  const submitMoment = questionnaireFlow.moments.find((s) => s.name === 'submits questionnaire');
+  expect(submitMoment?.type).toBe('command');
+  if (submitMoment?.type === 'command') {
+    const example = submitMoment.server?.specs?.[0]?.rules[0]?.examples[0];
     const whenStep = example?.steps?.find((s) => s.keyword === 'When');
     if (whenStep && 'text' in whenStep) {
       expect(whenStep.text).toBe('SubmitQuestionnaire');
@@ -866,10 +868,10 @@ function validateQuestionAnsweredEvent(model: Model): void {
   expect(questionAnsweredMessage?.type).toBe('event');
 }
 
-function validateGivenSectionEventRefs(questionnaireFlow: Narrative): void {
-  const viewsSlice = questionnaireFlow.slices.find((s) => s.name === 'views progress');
-  if (viewsSlice?.type === 'query') {
-    const example = viewsSlice.server?.specs?.[0]?.rules[0]?.examples[0];
+function validateGivenSectionEventRefs(questionnaireFlow: Scene): void {
+  const viewsMoment = questionnaireFlow.moments.find((s) => s.name === 'views progress');
+  if (viewsMoment?.type === 'query') {
+    const example = viewsMoment.server?.specs?.[0]?.rules[0]?.examples[0];
     if (example?.steps !== undefined && Array.isArray(example.steps)) {
       const givenStep = example.steps.find((s) => s.keyword === 'Given');
       if (givenStep && 'text' in givenStep) {
@@ -957,7 +959,7 @@ async function createQuestionnaireBugTestModel(): Promise<Model> {
   const memoryVfs = new InMemoryFileStore();
   const questionnaireFlowContent = getQuestionnaireFlowContent();
   await memoryVfs.write('/test/questionnaires-bug.narrative.ts', new TextEncoder().encode(questionnaireFlowContent));
-  const flows = await getNarratives({ vfs: memoryVfs, root: '/test', pattern, fastFsScan: true });
+  const flows = await getScenes({ vfs: memoryVfs, root: '/test', pattern, fastFsScan: true });
   return flows.toModel();
 }
 
@@ -967,7 +969,7 @@ import {
   command,
   query,
   experience,
-  flow,
+  scene,
   describe,
   it,
   specs,
@@ -1017,7 +1019,7 @@ type SubmitQuestionnaire = Command<
   }
 >;
 
-flow('Questionnaires', 'Q9m2Kp4Lx', () => {
+scene('Questionnaires', 'Q9m2Kp4Lx', () => {
   command('sends the questionnaire link', 'S2b5Cp7Dz')
     .server(() => {
       specs(() => {
@@ -1086,15 +1088,15 @@ flow('Questionnaires', 'Q9m2Kp4Lx', () => {
 
 function validateQuestionnaireBugFix(model: Model): void {
   const questionnaireFlow = getQuestionnaireFlowFromModel(model);
-  const submitSlice = getSubmitSlice(questionnaireFlow);
-  const submitExample = getSubmitExample(submitSlice);
+  const submitMoment = getSubmitMoment(questionnaireFlow);
+  const submitExample = getSubmitExample(submitMoment);
 
   validateSubmitCommandRef(submitExample);
-  validateLinkSliceCommandRef(questionnaireFlow);
+  validateLinkMomentCommandRef(questionnaireFlow);
 }
 
-function getQuestionnaireFlowFromModel(model: Model): Narrative {
-  const questionnaireFlow = model.narratives.find((f) => f.name === 'Questionnaires');
+function getQuestionnaireFlowFromModel(model: Model): Scene {
+  const questionnaireFlow = model.scenes.find((f) => f.name === 'Questionnaires');
   expect(questionnaireFlow).toBeDefined();
   if (questionnaireFlow === null || questionnaireFlow === undefined) {
     throw new Error('Questionnaire flow not found');
@@ -1102,26 +1104,26 @@ function getQuestionnaireFlowFromModel(model: Model): Narrative {
   return questionnaireFlow;
 }
 
-function getSubmitSlice(questionnaireFlow: Narrative): {
+function getSubmitMoment(questionnaireFlow: Scene): {
   type: 'command';
   server: { specs: { type: 'gherkin'; feature: string; rules: { examples: unknown[] }[] }[] };
 } {
-  const submitSlice = questionnaireFlow.slices.find((s) => s.name === 'submits the questionnaire');
-  expect(submitSlice).toBeDefined();
-  expect(submitSlice?.type).toBe('command');
-  if (submitSlice?.type !== 'command') {
+  const submitMoment = questionnaireFlow.moments.find((s) => s.name === 'submits the questionnaire');
+  expect(submitMoment).toBeDefined();
+  expect(submitMoment?.type).toBe('command');
+  if (submitMoment?.type !== 'command') {
     throw new Error('Submit slice is not a command');
   }
-  return submitSlice as {
+  return submitMoment as {
     type: 'command';
     server: { specs: { type: 'gherkin'; feature: string; rules: { examples: unknown[] }[] }[] };
   };
 }
 
-function getSubmitExample(submitSlice: {
+function getSubmitExample(submitMoment: {
   server: { specs: { type: 'gherkin'; feature: string; rules: { examples: unknown[] }[] }[] };
 }): unknown {
-  const rule = submitSlice.server?.specs?.[0]?.rules[0];
+  const rule = submitMoment.server?.specs?.[0]?.rules[0];
   expect(rule).toBeDefined();
   expect(rule?.examples).toHaveLength(1);
   const example = rule?.examples[0];
@@ -1141,11 +1143,11 @@ function validateSubmitCommandRef(example: unknown): void {
   }
 }
 
-function validateLinkSliceCommandRef(questionnaireFlow: Narrative): void {
-  const linkSlice = questionnaireFlow.slices.find((s) => s.name === 'sends the questionnaire link');
-  expect(linkSlice?.type).toBe('command');
-  if (linkSlice?.type === 'command') {
-    const linkExample = linkSlice.server?.specs?.[0]?.rules[0]?.examples[0];
+function validateLinkMomentCommandRef(questionnaireFlow: Scene): void {
+  const linkMoment = questionnaireFlow.moments.find((s) => s.name === 'sends the questionnaire link');
+  expect(linkMoment?.type).toBe('command');
+  if (linkMoment?.type === 'command') {
+    const linkExample = linkMoment.server?.specs?.[0]?.rules[0]?.examples[0];
     const ex = linkExample as { steps?: { keyword: string; text?: string }[] };
     const whenStep = ex?.steps?.find((s) => s.keyword === 'When');
     if (whenStep && 'text' in whenStep) {
@@ -1156,8 +1158,8 @@ function validateLinkSliceCommandRef(questionnaireFlow: Narrative): void {
 
 function validateCommandRef(model: Model): void {
   const questionnaireFlow = getQuestionnaireFlowFromModel(model);
-  const submitSlice = getSubmitSliceFromFlow(questionnaireFlow);
-  const serverSpecs = getServerSpecsFromSlice(submitSlice);
+  const submitMoment = getSubmitMomentFromFlow(questionnaireFlow);
+  const serverSpecs = getServerSpecsFromMoment(submitMoment);
   const rule = getFirstRuleFromSpecs(serverSpecs);
   const example = getFirstExampleFromRule(rule);
 
@@ -1165,18 +1167,18 @@ function validateCommandRef(model: Model): void {
   validateThenEvents(example);
 }
 
-function getSubmitSliceFromFlow(questionnaireFlow: Narrative): unknown {
-  const submitSlice = questionnaireFlow.slices.find((s) => s.name === 'submits the questionnaire');
-  expect(submitSlice).toBeDefined();
-  expect(submitSlice?.type).toBe('command');
-  if (submitSlice?.type !== 'command') {
+function getSubmitMomentFromFlow(questionnaireFlow: Scene): unknown {
+  const submitMoment = questionnaireFlow.moments.find((s) => s.name === 'submits the questionnaire');
+  expect(submitMoment).toBeDefined();
+  expect(submitMoment?.type).toBe('command');
+  if (submitMoment?.type !== 'command') {
     throw new Error('Submit slice is not a command');
   }
-  return submitSlice;
+  return submitMoment;
 }
 
-function getServerSpecsFromSlice(submitSlice: unknown): unknown {
-  const slice = submitSlice as { server?: { specs?: unknown[] } };
+function getServerSpecsFromMoment(submitMoment: unknown): unknown {
+  const slice = submitMoment as { server?: { specs?: unknown[] } };
   const serverSpecs = slice.server?.specs;
   expect(serverSpecs).toBeDefined();
   expect(Array.isArray(serverSpecs)).toBe(true);
@@ -1242,16 +1244,16 @@ function validateThenEvents(example: unknown): void {
 }
 
 describe('modules in toModel()', () => {
-  it('should derive modules from narratives with different sourceFiles', async () => {
+  it('should derive modules from scenes with different sourceFiles', async () => {
     const memoryVfs = new InMemoryFileStore();
 
     const ordersContent = `
-import { flow, command, specs, rule, example, type Command, type Event } from '@auto-engineer/narrative';
+import { scene, command, specs, rule, example, type Command, type Event } from '@auto-engineer/narrative';
 
 type CreateOrder = Command<'CreateOrder', { orderId: string }>;
 type OrderCreated = Event<'OrderCreated', { orderId: string; createdAt: Date }>;
 
-flow('Orders', () => {
+scene('Orders', () => {
   command('create order')
     .server(() => {
       specs(() => {
@@ -1266,12 +1268,12 @@ flow('Orders', () => {
 `;
 
     const usersContent = `
-import { flow, command, specs, rule, example, type Command, type Event } from '@auto-engineer/narrative';
+import { scene, command, specs, rule, example, type Command, type Event } from '@auto-engineer/narrative';
 
 type CreateUser = Command<'CreateUser', { userId: string; name: string }>;
 type UserCreated = Event<'UserCreated', { userId: string; name: string; createdAt: Date }>;
 
-flow('Users', () => {
+scene('Users', () => {
   command('create user')
     .server(() => {
       specs(() => {
@@ -1288,7 +1290,7 @@ flow('Users', () => {
     await memoryVfs.write('/test/orders.narrative.ts', new TextEncoder().encode(ordersContent));
     await memoryVfs.write('/test/users.narrative.ts', new TextEncoder().encode(usersContent));
 
-    const flows = await getNarratives({
+    const flows = await getScenes({
       vfs: memoryVfs,
       root: '/test',
       pattern: /\.narrative\.ts$/,
@@ -1317,12 +1319,12 @@ flow('Users', () => {
     const memoryVfs = new InMemoryFileStore();
 
     const content = `
-import { flow, command, specs, rule, example, type Command, type Event } from '@auto-engineer/narrative';
+import { scene, command, specs, rule, example, type Command, type Event } from '@auto-engineer/narrative';
 
 type CreateOrder = Command<'CreateOrder', { orderId: string }>;
 type OrderCreated = Event<'OrderCreated', { orderId: string }>;
 
-flow('Orders', () => {
+scene('Orders', () => {
   command('create order')
     .server(() => {
       specs(() => {
@@ -1338,7 +1340,7 @@ flow('Orders', () => {
 
     await memoryVfs.write('/test/orders.narrative.ts', new TextEncoder().encode(content));
 
-    const flows = await getNarratives({
+    const flows = await getScenes({
       vfs: memoryVfs,
       root: '/test',
       pattern: /\.narrative\.ts$/,
@@ -1354,17 +1356,17 @@ flow('Orders', () => {
     expect(declaredNames).toContain('OrderCreated');
   });
 
-  it('should group narratives from same sourceFile into one module', async () => {
+  it('should group scenes from same sourceFile into one module', async () => {
     const memoryVfs = new InMemoryFileStore();
 
     const content = `
-import { flow, command, query, specs, rule, example, type Command, type Event, type State } from '@auto-engineer/narrative';
+import { scene, command, query, specs, rule, example, type Command, type Event, type State } from '@auto-engineer/narrative';
 
 type CreateTodo = Command<'CreateTodo', { todoId: string }>;
 type TodoCreated = Event<'TodoCreated', { todoId: string }>;
 type TodoList = State<'TodoList', { todos: string[] }>;
 
-flow('Create Todos', () => {
+scene('Create Todos', () => {
   command('add todo')
     .server(() => {
       specs(() => {
@@ -1377,7 +1379,7 @@ flow('Create Todos', () => {
     });
 });
 
-flow('View Todos', () => {
+scene('View Todos', () => {
   query('list todos')
     .server(() => {
       specs(() => {
@@ -1394,7 +1396,7 @@ flow('View Todos', () => {
 
     await memoryVfs.write('/test/todos.narrative.ts', new TextEncoder().encode(content));
 
-    const flows = await getNarratives({
+    const flows = await getScenes({
       vfs: memoryVfs,
       root: '/test',
       pattern: /\.narrative\.ts$/,
@@ -1403,23 +1405,23 @@ flow('View Todos', () => {
     const model = flows.toModel();
 
     expect(model.modules).toHaveLength(1);
-    expect(model.modules[0].contains.narrativeIds).toHaveLength(2);
+    expect(model.modules[0].contains.sceneIds).toHaveLength(2);
 
-    const narrativeNames = model.narratives.map((n) => n.name);
-    expect(narrativeNames).toContain('Create Todos');
-    expect(narrativeNames).toContain('View Todos');
+    const sceneNames = model.scenes.map((n) => n.name);
+    expect(sceneNames).toContain('Create Todos');
+    expect(sceneNames).toContain('View Todos');
   });
 
   it('should validate model with modules passes schema', async () => {
     const memoryVfs = new InMemoryFileStore();
 
     const content = `
-import { flow, command, specs, rule, example, type Command, type Event } from '@auto-engineer/narrative';
+import { scene, command, specs, rule, example, type Command, type Event } from '@auto-engineer/narrative';
 
 type DoSomething = Command<'DoSomething', { id: string }>;
 type SomethingDone = Event<'SomethingDone', { id: string }>;
 
-flow('Test', () => {
+scene('Test', () => {
   command('do something')
     .server(() => {
       specs(() => {
@@ -1435,7 +1437,7 @@ flow('Test', () => {
 
     await memoryVfs.write('/test/test.narrative.ts', new TextEncoder().encode(content));
 
-    const flows = await getNarratives({
+    const flows = await getScenes({
       vfs: memoryVfs,
       root: '/test',
       pattern: /\.narrative\.ts$/,
@@ -1457,12 +1459,12 @@ describe('projection DSL methods', () => {
   it('should generate correct origin for singleton projection', async () => {
     const memoryVfs = new InMemoryFileStore();
     const flowContent = `
-import { flow, query, specs, rule, example, data, source, type Event, type State } from '@auto-engineer/narrative';
+import { scene, query, specs, rule, example, data, source, type Event, type State } from '@auto-engineer/narrative';
 
 type TodoAdded = Event<'TodoAdded', { todoId: string; description: string; addedAt: Date }>;
 type TodoListSummary = State<'TodoListSummary', { summaryId: string; totalTodos: number }>;
 
-flow('Projection Test', () => {
+scene('Projection Test', () => {
   query('views summary')
     .server(() => {
       specs(() => {
@@ -1480,20 +1482,20 @@ flow('Projection Test', () => {
 
     await memoryVfs.write('/test/projection.narrative.ts', new TextEncoder().encode(flowContent));
 
-    const flows = await getNarratives({ vfs: memoryVfs, root: '/test', pattern, fastFsScan: true });
+    const flows = await getScenes({ vfs: memoryVfs, root: '/test', pattern, fastFsScan: true });
     const model = flows.toModel();
 
-    const projectionFlow = model.narratives.find((f) => f.name === 'Projection Test');
+    const projectionFlow = model.scenes.find((f) => f.name === 'Projection Test');
     expect(projectionFlow).toBeDefined();
 
     if (!projectionFlow) return;
 
-    const summarySlice = projectionFlow.slices.find((s) => s.name === 'views summary');
-    expect(summarySlice?.type).toBe('query');
+    const summaryMoment = projectionFlow.moments.find((s) => s.name === 'views summary');
+    expect(summaryMoment?.type).toBe('query');
 
-    if (summarySlice?.type !== 'query') return;
+    if (summaryMoment?.type !== 'query') return;
 
-    const data = summarySlice.server.data;
+    const data = summaryMoment.server.data;
     expect(data).toBeDefined();
     expect(data?.items).toHaveLength(1);
 
@@ -1509,12 +1511,12 @@ flow('Projection Test', () => {
   it('should generate correct origin for regular projection with single idField', async () => {
     const memoryVfs = new InMemoryFileStore();
     const flowContent = `
-import { flow, query, specs, rule, example, data, source, type Event, type State } from '@auto-engineer/narrative';
+import { scene, query, specs, rule, example, data, source, type Event, type State } from '@auto-engineer/narrative';
 
 type TodoAdded = Event<'TodoAdded', { todoId: string; description: string; addedAt: Date }>;
 type TodoState = State<'TodoState', { todoId: string; description: string; status: string }>;
 
-flow('Projection Test', () => {
+scene('Projection Test', () => {
   query('views todo')
     .server(() => {
       specs(() => {
@@ -1532,20 +1534,20 @@ flow('Projection Test', () => {
 
     await memoryVfs.write('/test/projection.narrative.ts', new TextEncoder().encode(flowContent));
 
-    const flows = await getNarratives({ vfs: memoryVfs, root: '/test', pattern, fastFsScan: true });
+    const flows = await getScenes({ vfs: memoryVfs, root: '/test', pattern, fastFsScan: true });
     const model = flows.toModel();
 
-    const projectionFlow = model.narratives.find((f) => f.name === 'Projection Test');
+    const projectionFlow = model.scenes.find((f) => f.name === 'Projection Test');
     expect(projectionFlow).toBeDefined();
 
     if (!projectionFlow) return;
 
-    const todoSlice = projectionFlow.slices.find((s) => s.name === 'views todo');
-    expect(todoSlice?.type).toBe('query');
+    const todoMoment = projectionFlow.moments.find((s) => s.name === 'views todo');
+    expect(todoMoment?.type).toBe('query');
 
-    if (todoSlice?.type !== 'query') return;
+    if (todoMoment?.type !== 'query') return;
 
-    const data = todoSlice.server.data;
+    const data = todoMoment.server.data;
     expect(data).toBeDefined();
     expect(data?.items).toHaveLength(1);
 
@@ -1561,12 +1563,12 @@ flow('Projection Test', () => {
   it('should generate correct origin for composite projection with multiple idFields', async () => {
     const memoryVfs = new InMemoryFileStore();
     const flowContent = `
-import { flow, query, specs, rule, example, data, source, type Event, type State } from '@auto-engineer/narrative';
+import { scene, query, specs, rule, example, data, source, type Event, type State } from '@auto-engineer/narrative';
 
 type UserProjectAssigned = Event<'UserProjectAssigned', { userId: string; projectId: string; assignedAt: Date }>;
 type UserProjectState = State<'UserProjectState', { userId: string; projectId: string; role: string }>;
 
-flow('Projection Test', () => {
+scene('Projection Test', () => {
   query('views user project')
     .server(() => {
       specs(() => {
@@ -1584,20 +1586,20 @@ flow('Projection Test', () => {
 
     await memoryVfs.write('/test/projection.narrative.ts', new TextEncoder().encode(flowContent));
 
-    const flows = await getNarratives({ vfs: memoryVfs, root: '/test', pattern, fastFsScan: true });
+    const flows = await getScenes({ vfs: memoryVfs, root: '/test', pattern, fastFsScan: true });
     const model = flows.toModel();
 
-    const projectionFlow = model.narratives.find((f) => f.name === 'Projection Test');
+    const projectionFlow = model.scenes.find((f) => f.name === 'Projection Test');
     expect(projectionFlow).toBeDefined();
 
     if (!projectionFlow) return;
 
-    const userProjectSlice = projectionFlow.slices.find((s) => s.name === 'views user project');
-    expect(userProjectSlice?.type).toBe('query');
+    const userProjectMoment = projectionFlow.moments.find((s) => s.name === 'views user project');
+    expect(userProjectMoment?.type).toBe('query');
 
-    if (userProjectSlice?.type !== 'query') return;
+    if (userProjectMoment?.type !== 'query') return;
 
-    const data = userProjectSlice.server.data;
+    const data = userProjectMoment.server.data;
     expect(data).toBeDefined();
     expect(data?.items).toHaveLength(1);
 
@@ -1613,7 +1615,7 @@ flow('Projection Test', () => {
   it('should validate all three projection patterns together', async () => {
     const memoryVfs = new InMemoryFileStore();
     const flowContent = `
-import { flow, query, specs, rule, example, data, source, type Event, type State } from '@auto-engineer/narrative';
+import { scene, query, specs, rule, example, data, source, type Event, type State } from '@auto-engineer/narrative';
 
 type TodoAdded = Event<'TodoAdded', { todoId: string; userId: string; projectId: string; description: string; addedAt: Date }>;
 
@@ -1621,7 +1623,7 @@ type TodoListSummary = State<'TodoListSummary', { summaryId: string; totalTodos:
 type TodoState = State<'TodoState', { todoId: string; description: string; status: string }>;
 type UserProjectTodos = State<'UserProjectTodos', { userId: string; projectId: string; todos: string[] }>;
 
-flow('All Projection Patterns', () => {
+scene('All Projection Patterns', () => {
   query('views summary')
     .server(() => {
       specs(() => {
@@ -1665,7 +1667,7 @@ flow('All Projection Patterns', () => {
 
     await memoryVfs.write('/test/projection.narrative.ts', new TextEncoder().encode(flowContent));
 
-    const flows = await getNarratives({ vfs: memoryVfs, root: '/test', pattern, fastFsScan: true });
+    const flows = await getScenes({ vfs: memoryVfs, root: '/test', pattern, fastFsScan: true });
     const model = flows.toModel();
 
     const parseResult = modelSchema.safeParse(model);
@@ -1674,16 +1676,16 @@ flow('All Projection Patterns', () => {
     }
     expect(parseResult.success).toBe(true);
 
-    const projectionFlow = model.narratives.find((f) => f.name === 'All Projection Patterns');
+    const projectionFlow = model.scenes.find((f) => f.name === 'All Projection Patterns');
     expect(projectionFlow).toBeDefined();
 
     if (!projectionFlow) return;
 
-    expect(projectionFlow.slices).toHaveLength(3);
+    expect(projectionFlow.moments).toHaveLength(3);
 
-    const summarySlice = projectionFlow.slices.find((s) => s.name === 'views summary');
-    if (summarySlice?.type === 'query') {
-      const data = summarySlice.server.data;
+    const summaryMoment = projectionFlow.moments.find((s) => s.name === 'views summary');
+    if (summaryMoment?.type === 'query') {
+      const data = summaryMoment.server.data;
       expect(data?.items?.[0].origin).toMatchObject({
         type: 'projection',
         name: 'TodoSummary',
@@ -1691,9 +1693,9 @@ flow('All Projection Patterns', () => {
       });
     }
 
-    const todoSlice = projectionFlow.slices.find((s) => s.name === 'views todo');
-    if (todoSlice?.type === 'query') {
-      const data = todoSlice.server.data;
+    const todoMoment = projectionFlow.moments.find((s) => s.name === 'views todo');
+    if (todoMoment?.type === 'query') {
+      const data = todoMoment.server.data;
       expect(data?.items?.[0].origin).toMatchObject({
         type: 'projection',
         name: 'Todos',
@@ -1701,9 +1703,9 @@ flow('All Projection Patterns', () => {
       });
     }
 
-    const userProjectSlice = projectionFlow.slices.find((s) => s.name === 'views user project todos');
-    if (userProjectSlice?.type === 'query') {
-      const data = userProjectSlice.server.data;
+    const userProjectMoment = projectionFlow.moments.find((s) => s.name === 'views user project todos');
+    if (userProjectMoment?.type === 'query') {
+      const data = userProjectMoment.server.data;
       expect(data?.items?.[0].origin).toMatchObject({
         type: 'projection',
         name: 'UserProjectTodos',
@@ -1716,12 +1718,12 @@ flow('All Projection Patterns', () => {
     const memoryVfs = new InMemoryFileStore();
 
     const flowContent = `
-import { flow, command, query, specs, rule, example, data, sink, source, type Event, type State } from '@auto-engineer/narrative';
+import { scene, command, query, specs, rule, example, data, sink, source, type Event, type State } from '@auto-engineer/narrative';
 
 type OrderPlaced = Event<'OrderPlaced', { orderId: string; amount: number }>;
 type OrderState = State<'OrderState', { orderId: string; status: string }>;
 
-flow('Data Item IDs', () => {
+scene('Data Item IDs', () => {
   command('places order')
     .server(() => {
       specs(() => {
@@ -1755,41 +1757,41 @@ flow('Data Item IDs', () => {
 
     await memoryVfs.write('/test/data-ids.narrative.ts', new TextEncoder().encode(flowContent));
 
-    const flows = await getNarratives({ vfs: memoryVfs, root: '/test', pattern, fastFsScan: true });
+    const flows = await getScenes({ vfs: memoryVfs, root: '/test', pattern, fastFsScan: true });
     const model = flows.toModel();
 
     const parseResult = modelSchema.safeParse(model);
     expect(parseResult.success).toBe(true);
 
-    const dataIdsFlow = model.narratives.find((f) => f.name === 'Data Item IDs');
+    const dataIdsFlow = model.scenes.find((f) => f.name === 'Data Item IDs');
     expect(dataIdsFlow).toBeDefined();
 
     if (!dataIdsFlow) return;
 
-    const commandSlice = dataIdsFlow.slices.find((s) => s.name === 'places order');
-    if (commandSlice?.type === 'command') {
-      const sinkData = commandSlice.server.data;
+    const commandMoment = dataIdsFlow.moments.find((s) => s.name === 'places order');
+    if (commandMoment?.type === 'command') {
+      const sinkData = commandMoment.server.data;
       expect(sinkData?.items).toHaveLength(1);
       expect(sinkData?.items?.[0].id).toBe('SINK-001');
     }
 
-    const querySlice = dataIdsFlow.slices.find((s) => s.name === 'views order status');
-    if (querySlice?.type === 'query') {
-      const sourceData = querySlice.server.data;
+    const queryMoment = dataIdsFlow.moments.find((s) => s.name === 'views order status');
+    if (queryMoment?.type === 'query') {
+      const sourceData = queryMoment.server.data;
       expect(sourceData?.items).toHaveLength(1);
       expect(sourceData?.items?.[0].id).toBe('SOURCE-001');
     }
   });
 });
 
-describe('round-trip: model -> narrative code -> VFS -> getNarratives -> toModel', { timeout: 30_000 }, () => {
+describe('round-trip: model -> narrative code -> VFS -> getScenes -> toModel', { timeout: 30_000 }, () => {
   it('preserves step text values through full round-trip', async () => {
     const inputModel: Model = {
       variant: 'specs',
-      narratives: [
+      scenes: [
         {
           name: 'Stay management',
-          slices: [
+          moments: [
             {
               type: 'command',
               name: 'Publish stay',
@@ -1865,14 +1867,14 @@ describe('round-trip: model -> narrative code -> VFS -> getNarratives -> toModel
     const generated = await modelToNarrative(inputModel);
 
     const vfs = new InMemoryFileStore();
-    clearGetNarrativesCache();
+    clearGetScenesCache();
 
     for (const file of generated.files) {
       const filePath = `/project/${file.path}`;
       await vfs.write(filePath, new TextEncoder().encode(file.code));
     }
 
-    const result = await getNarratives({
+    const result = await getScenes({
       vfs,
       root: '/project',
       pattern: /\.(narrative)\.(ts)$/,
@@ -1881,12 +1883,12 @@ describe('round-trip: model -> narrative code -> VFS -> getNarratives -> toModel
 
     const roundTrippedModel = result.toModel();
 
-    const stayNarrative = roundTrippedModel.narratives.find((n) => n.name === 'Stay management');
-    const publishSlice = stayNarrative!.slices.find((s) => s.name === 'Publish stay');
-    expect(publishSlice!.type).toBe('command');
+    const stayNarrative = roundTrippedModel.scenes.find((n) => n.name === 'Stay management');
+    const publishMoment = stayNarrative!.moments.find((s) => s.name === 'Publish stay');
+    expect(publishMoment!.type).toBe('command');
 
-    if (publishSlice?.type === 'command') {
-      const example = publishSlice.server.specs[0].rules[0].examples[0];
+    if (publishMoment?.type === 'command') {
+      const example = publishMoment.server.specs[0].rules[0].examples[0];
       expect(example.steps).toEqual([
         { keyword: 'Given', text: 'StayCreated', docString: { stayId: 'stay_1', title: 'Beach house' } },
         { keyword: 'When', text: 'PublishStay', docString: { stayId: 'stay_1' } },
@@ -1902,10 +1904,10 @@ describe('round-trip: model -> narrative code -> VFS -> getNarratives -> toModel
   it('preserves step text with multiple given events and multiple examples', async () => {
     const inputModel: Model = {
       variant: 'specs',
-      narratives: [
+      scenes: [
         {
           name: 'Order processing',
-          slices: [
+          moments: [
             {
               type: 'command',
               name: 'Complete order',
@@ -2022,14 +2024,14 @@ describe('round-trip: model -> narrative code -> VFS -> getNarratives -> toModel
     const generated = await modelToNarrative(inputModel);
 
     const vfs = new InMemoryFileStore();
-    clearGetNarrativesCache();
+    clearGetScenesCache();
 
     for (const file of generated.files) {
       const filePath = `/project/${file.path}`;
       await vfs.write(filePath, new TextEncoder().encode(file.code));
     }
 
-    const result = await getNarratives({
+    const result = await getScenes({
       vfs,
       root: '/project',
       pattern: /\.(narrative)\.(ts)$/,
@@ -2038,12 +2040,12 @@ describe('round-trip: model -> narrative code -> VFS -> getNarratives -> toModel
 
     const roundTrippedModel = result.toModel();
 
-    const orderNarrative = roundTrippedModel.narratives.find((n) => n.name === 'Order processing');
-    const completeSlice = orderNarrative!.slices.find((s) => s.name === 'Complete order');
-    expect(completeSlice!.type).toBe('command');
+    const orderNarrative = roundTrippedModel.scenes.find((n) => n.name === 'Order processing');
+    const completeMoment = orderNarrative!.moments.find((s) => s.name === 'Complete order');
+    expect(completeMoment!.type).toBe('command');
 
-    if (completeSlice?.type === 'command') {
-      const examples = completeSlice.server.specs[0].rules[0].examples;
+    if (completeMoment?.type === 'command') {
+      const examples = completeMoment.server.specs[0].rules[0].examples;
 
       expect(examples[0].steps).toEqual([
         { keyword: 'Given', text: 'OrderCreated', docString: { orderId: 'ord_1', customerId: 'cust_1' } },
@@ -2064,14 +2066,14 @@ describe('round-trip: model -> narrative code -> VFS -> getNarratives -> toModel
     }
   });
 
-  it('preserves step text with multiple narratives in separate modules', async () => {
+  it('preserves step text with multiple scenes in separate modules', async () => {
     const inputModel: Model = {
       variant: 'specs',
-      narratives: [
+      scenes: [
         {
           name: 'Stays',
           sourceFile: 'stays.narrative.ts',
-          slices: [
+          moments: [
             {
               type: 'command',
               name: 'Create stay',
@@ -2115,7 +2117,7 @@ describe('round-trip: model -> narrative code -> VFS -> getNarratives -> toModel
         {
           name: 'Bookings',
           sourceFile: 'bookings.narrative.ts',
-          slices: [
+          moments: [
             {
               type: 'command',
               name: 'Book stay',
@@ -2213,7 +2215,7 @@ describe('round-trip: model -> narrative code -> VFS -> getNarratives -> toModel
         {
           sourceFile: 'stays.narrative.ts',
           isDerived: true,
-          contains: { narrativeIds: [] },
+          contains: { sceneIds: [] },
           declares: {
             messages: [
               { kind: 'command', name: 'CreateStay' },
@@ -2224,7 +2226,7 @@ describe('round-trip: model -> narrative code -> VFS -> getNarratives -> toModel
         {
           sourceFile: 'bookings.narrative.ts',
           isDerived: true,
-          contains: { narrativeIds: [] },
+          contains: { sceneIds: [] },
           declares: {
             messages: [
               { kind: 'event', name: 'StayPublished' },
@@ -2239,14 +2241,14 @@ describe('round-trip: model -> narrative code -> VFS -> getNarratives -> toModel
     const generated = await modelToNarrative(inputModel);
 
     const vfs = new InMemoryFileStore();
-    clearGetNarrativesCache();
+    clearGetScenesCache();
 
     for (const file of generated.files) {
       const filePath = `/project/${file.path}`;
       await vfs.write(filePath, new TextEncoder().encode(file.code));
     }
 
-    const result = await getNarratives({
+    const result = await getScenes({
       vfs,
       root: '/project',
       pattern: /\.(narrative)\.(ts)$/,
@@ -2255,12 +2257,12 @@ describe('round-trip: model -> narrative code -> VFS -> getNarratives -> toModel
 
     const roundTrippedModel = result.toModel();
 
-    const bookingsNarrative = roundTrippedModel.narratives.find((n) => n.name === 'Bookings');
-    const bookSlice = bookingsNarrative!.slices.find((s) => s.name === 'Book stay');
-    expect(bookSlice!.type).toBe('command');
+    const bookingsNarrative = roundTrippedModel.scenes.find((n) => n.name === 'Bookings');
+    const bookMoment = bookingsNarrative!.moments.find((s) => s.name === 'Book stay');
+    expect(bookMoment!.type).toBe('command');
 
-    if (bookSlice?.type === 'command') {
-      const example = bookSlice.server.specs[0].rules[0].examples[0];
+    if (bookMoment?.type === 'command') {
+      const example = bookMoment.server.specs[0].rules[0].examples[0];
       expect(example.steps).toEqual([
         {
           keyword: 'Given',
@@ -2276,12 +2278,12 @@ describe('round-trip: model -> narrative code -> VFS -> getNarratives -> toModel
       ]);
     }
 
-    const staysNarrative = roundTrippedModel.narratives.find((n) => n.name === 'Stays');
-    const createSlice = staysNarrative!.slices.find((s) => s.name === 'Create stay');
-    expect(createSlice!.type).toBe('command');
+    const staysNarrative = roundTrippedModel.scenes.find((n) => n.name === 'Stays');
+    const createMoment = staysNarrative!.moments.find((s) => s.name === 'Create stay');
+    expect(createMoment!.type).toBe('command');
 
-    if (createSlice?.type === 'command') {
-      const example = createSlice.server.specs[0].rules[0].examples[0];
+    if (createMoment?.type === 'command') {
+      const example = createMoment.server.specs[0].rules[0].examples[0];
       expect(example.steps).toEqual([
         { keyword: 'When', text: 'CreateStay', docString: { stayId: 'stay_1', title: 'Cozy cabin' } },
         { keyword: 'Then', text: 'StayCreated', docString: { stayId: 'stay_1', title: 'Cozy cabin' } },