eventmodeler 0.4.6 → 0.4.7

package/dist/api/index.d.ts

@@ -143,6 +143,9 @@ export declare function removeScenario(modelId: string, scenarioName: string, sl
 export declare function createFlow(modelId: string, fromName: string, toName: string): Promise<{
     success: boolean;
 }>;
+export declare function removeFlow(modelId: string, fromName: string, toName: string): Promise<{
+    flowId: string;
+}>;
 export interface CompoundFieldInput {
     name: string;
     fieldType: string;

package/dist/api/index.js

@@ -206,6 +206,9 @@ export async function removeScenario(modelId, scenarioName, sliceName) {
 export async function createFlow(modelId, fromName, toName) {
     return cliPost('/cli/create-flow', { modelId, fromName, toName });
 }
+export async function removeFlow(modelId, fromName, toName) {
+    return cliPost('/cli/remove-flow', { modelId, fromName, toName });
+}
 export async function createStateChangeSlice(modelId, input) {
     return cliPost('/cli/create-state-change-slice', { modelId, ...input });
 }

package/dist/eventmodeler.js

@@ -4413,7 +4413,8 @@ EXAMPLES:
         process.exit(1);
       }
       {
-        const response = await search(modelId, subcommand);
+        const searchTerm = target ? `${subcommand} ${target}` : subcommand;
+        const response = await search(modelId, searchTerm);
         if (format === "json") {
           console.log(JSON.stringify(response, null, 2));
         } else {
@@ -4441,7 +4442,7 @@ EXAMPLES:
               attrs["@_parent-chapter-name"] = r.parentChapterName;
             return `  ${xb.build({ [tag]: attrs }).trim()}`;
           });
-          const wrapper = xb.build({ "search-results": { "@_query": subcommand, "@_count": String(response.results.length) } });
+          const wrapper = xb.build({ "search-results": { "@_query": searchTerm, "@_count": String(response.results.length) } });
           const open = wrapper.replace(/\/>$/, ">").trim();
           console.log([open, ...results, "</search-results>"].join(`
 `));

package/dist/index.js

@@ -10,6 +10,7 @@ const VERSION = packageJson.version;
 // Utilities
 import { openApp } from './slices/open-app/index.js';
 import { parseScenarioInput } from './slices/add-scenario/index.js';
+import { runGuide } from './slices/guide/index.js';
 import { login } from './slices/login/index.js';
 import { logout } from './slices/logout/index.js';
 import { whoami } from './slices/whoami/index.js';
@@ -124,6 +125,10 @@ COMMANDS:
 
   export json                    Export entire model as JSON
 
+GUIDES:
+  guide                          List available guides for AI agents and users
+  guide <name>                   Read a conceptual guide (no auth required)
+
 OPTIONS:
   --format <xml|json>            Output format (default: xml, or from config)
   -h, --help                     Show this help message
@@ -277,6 +282,10 @@ EXAMPLES:
         await init();
         return;
     }
+    if (command === 'guide') {
+        runGuide(subcommand);
+        return;
+    }
     const projectConfig = loadProjectConfig();
     if (!projectConfig || projectConfig.type !== 'cloud') {
         console.error('Error: No project configured.');
@@ -1084,7 +1093,8 @@ EXAMPLES:
                 process.exit(1);
             }
             {
-                const response = await api.search(modelId, subcommand);
+                const searchTerm = target ? `${subcommand} ${target}` : subcommand;
+                const response = await api.search(modelId, searchTerm);
                 if (format === 'json') {
                     console.log(JSON.stringify(response, null, 2));
                 }
@@ -1113,7 +1123,7 @@ EXAMPLES:
                             attrs['@_parent-chapter-name'] = r.parentChapterName;
                         return `  ${xb.build({ [tag]: attrs }).trim()}`;
                     });
-                    const wrapper = xb.build({ 'search-results': { '@_query': subcommand, '@_count': String(response.results.length) } });
+                    const wrapper = xb.build({ 'search-results': { '@_query': searchTerm, '@_count': String(response.results.length) } });
                     // Replace self-closing tag with children
                     const open = wrapper.replace(/\/>$/, '>').trim();
                     console.log([open, ...results, '</search-results>'].join('\n'));
@@ -1505,18 +1515,19 @@ EXAMPLES:
                     {
                         // Parse field data
                         let field;
+                        const toApiFieldFromJson = (f) => ({
+                            name: f.name,
+                            fieldType: f.type ?? f.fieldType ?? 'String',
+                            isList: f.isList,
+                            isOptional: f.isOptional,
+                            isGenerated: f.isGenerated,
+                            isUserInput: f.isUserInput,
+                            subfields: f.subfields?.map(toApiFieldFromJson),
+                        });
                         try {
                             if (jsonArg) {
                                 const parsed = JSON.parse(inputData);
-                                field = {
-                                    name: parsed.name,
-                                    fieldType: parsed.type ?? parsed.fieldType ?? 'String',
-                                    isList: parsed.isList,
-                                    isOptional: parsed.isOptional,
-                                    isGenerated: parsed.isGenerated,
-                                    isUserInput: parsed.isUserInput,
-                                    subfields: parsed.subfields,
-                                };
+                                field = toApiFieldFromJson(parsed);
                             }
                             else {
                                 const parser = await import('./lib/slice-utils.js');
@@ -1562,6 +1573,7 @@ USAGE:
 TYPES:
   scenario   Remove a scenario from a slice
   field      Remove a field from an entity
+  flow       Remove a flow between elements
 
 Run "eventmodeler remove <type> --help" for type-specific help.
 `);
@@ -1646,9 +1658,39 @@ EXAMPLES:
                     }
                     break;
                 }
+                case 'flow': {
+                    if (helpRequested) {
+                        console.log(`
+eventmodeler remove flow - Remove a flow between elements
+
+USAGE:
+  eventmodeler remove flow --from <source> --to <target>
+
+OPTIONS:
+  --from <name>   Source element name (required)
+  --to <name>     Target element name (required)
+
+EXAMPLES:
+  eventmodeler remove flow --from OrderPlaced --to OrderSummary
+  eventmodeler remove flow --from "Order Summary" --to "Order Dashboard Screen"
+`);
+                        process.exit(0);
+                    }
+                    const fromArg = getNamedArg(filteredArgs, '--from');
+                    const toArg = getNamedArg(filteredArgs, '--to');
+                    if (!fromArg || !toArg) {
+                        console.error('Error: --from and --to are required');
+                        console.error('Usage: eventmodeler remove flow --from <source> --to <target>');
+                        console.error('Run "eventmodeler remove flow --help" for more information.');
+                        process.exit(1);
+                    }
+                    await api.removeFlow(modelId, fromArg, toArg);
+                    console.log(`Removed flow from "${fromArg}" to "${toArg}"`);
+                    break;
+                }
                 default:
                     console.error(`Unknown remove target: ${subcommand}`);
-                    console.error('Valid targets: scenario, field');
+                    console.error('Valid targets: scenario, field, flow');
                     console.error('Run "eventmodeler remove --help" for more information.');
                     process.exit(1);
             }
@@ -1791,7 +1833,7 @@ OPTIONS:
   <element-name>           Name of the command, event, read model, screen, or processor
 
 REQUIRED:
-  --field <name>           Field to update
+  --field <name>           Field to update (use dot-notation for nested subfields: "parent.child")
 
 UPDATE OPTIONS (at least one required):
   --optional true|false    Set isOptional flag
@@ -1816,6 +1858,9 @@ EXAMPLES:
 
   # Change field type
   eventmodeler update field OrderPlaced --field amount --type Decimal
+
+  # Update a nested subfield using dot-notation
+  eventmodeler update field OrderPlaced --field "shippingAddress.zipCode" --optional true
 `);
                         process.exit(0);
                     }

package/dist/slices/guide/guides/codegen.d.ts

@@ -0,0 +1,5 @@
+export declare const meta: {
+    name: string;
+    description: string;
+};
+export declare const content = "\n# Building Code Generators for Event Models\n\nThe `eventmodeler codegen` commands output structured JSON that code generators can consume:\n- `eventmodeler codegen slice \"<slice-name>\"` for per-slice generation\n- `eventmodeler codegen events [--chapter \"<chapter-name>\"]` for deduplicated event scaffolding across slices\n\n## The Codegen Pipeline\n\nPer-slice pipeline:\n\n```\neventmodeler codegen slice \"Place Order\" | your-generator > output-files\n```\n\nEvents-only pipeline:\n\n```\neventmodeler codegen events --chapter \"Register Products\" | your-events-generator > events.kt\n```\n\nYour generator receives JSON on stdin and produces code files.\n\n## Understanding the Input\n\nRun codegen to see what you'll receive:\n\n```bash\neventmodeler codegen slice \"Place Order\"\n```\n\n### Top-Level Structure\n\n```json\n{\n  \"sliceType\": \"STATE_CHANGE | STATE_VIEW | AUTOMATION\",\n  \"slice\": { \"id\": \"...\", \"name\": \"Place Order\" },\n  \"chapter\": { \"name\": \"...\", \"hierarchy\": [\"Parent\", \"Child\"] },\n  \"elements\": { ... },\n  \"inboundDependencies\": [ ... ],\n  \"internalFlows\": [ ... ],\n  \"scenarios\": [ ... ]\n}\n```\n\n### Events-Only Structure (`codegen events`)\n\n```json\n{\n  \"chapter\": { \"name\": \"Register Products\", \"parent\": { \"name\": \"Configuration\" } },\n  \"sliceCount\": 4,\n  \"eventCount\": 9,\n  \"slices\": [\n    { \"id\": \"...\", \"name\": \"Place Product\", \"sliceType\": \"STATE_CHANGE\" }\n  ],\n  \"events\": [\n    {\n      \"id\": \"...\",\n      \"name\": \"ProductRegistered\",\n      \"fields\": [ ... ],\n      \"aggregate\": \"Product\",\n      \"sourceSlices\": [\"Place Product\", \"Import Product\"]\n    }\n  ]\n}\n```\n\nUse `codegen events` when generating shared event artifacts in one pass (for a chapter or entire model).\n\n### Slice Types and What to Generate\n\n| sliceType | Components | Generate |\n|-----------|------------|----------|\n| `STATE_CHANGE` | Screen, Command, Event | API endpoint, command handler, event, tests |\n| `STATE_VIEW` | ReadModel | Projection/denormalizer, query endpoint |\n| `AUTOMATION` | Processor, ReadModel, Command, Event | Event handler, saga/process manager |\n\n## Building a Generator: Step by Step\n\n### 1. Parse the Input\n\n```typescript\n// generator.ts\nimport { stdin } from 'process';\n\ninterface CodegenInput {\n  sliceType: 'STATE_CHANGE' | 'STATE_VIEW' | 'AUTOMATION';\n  slice: { id: string; name: string };\n  elements: {\n    commands: Array<{ name: string; fields: Field[] }>;\n    events: Array<{ name: string; fields: Field[]; aggregate?: string }>;\n    readModels: Array<{ name: string; fields: Field[] }>;\n    screens: Array<{ name: string; fields: Field[] }>;\n    processors: Array<{ name: string }>;\n  };\n  inboundDependencies: InboundDependency[];\n  internalFlows: Flow[];\n  scenarios: Scenario[];\n}\n\nasync function readInput(): Promise<CodegenInput> {\n  const chunks: Buffer[] = [];\n  for await (const chunk of stdin) {\n    chunks.push(chunk);\n  }\n  return JSON.parse(Buffer.concat(chunks).toString());\n}\n```\n\n### 2. Route by Slice Type\n\n```typescript\nasync function main() {\n  const input = await readInput();\n\n  switch (input.sliceType) {\n    case 'STATE_CHANGE':\n      generateStateChangeSlice(input);\n      break;\n    case 'STATE_VIEW':\n      generateStateViewSlice(input);\n      break;\n    case 'AUTOMATION':\n      generateAutomationSlice(input);\n      break;\n  }\n}\n```\n\n### 3. Generate from Elements\n\n**Commands \u2192 DTOs/Request types:**\n```typescript\nfunction generateCommand(cmd: Command): string {\n  const fields = cmd.fields\n    .map(f => `  ${f.name}: ${mapType(f.type)}${f.optional ? ' | null' : ''};`)\n    .join('\\n');\n\n  return `export interface ${cmd.name}Command {\\n${fields}\\n}`;\n}\n```\n\n**Events \u2192 Event types with metadata:**\n```typescript\nfunction generateEvent(evt: Event): string {\n  const fields = evt.fields.map(f => {\n    const generated = f.generated ? ' // generated' : '';\n    return `  ${f.name}: ${mapType(f.type)};${generated}`;\n  }).join('\\n');\n\n  return `export interface ${evt.name}Event {\\n  type: '${evt.name}';\\n${fields}\\n}`;\n}\n```\n\n**ReadModels \u2192 Projection types:**\n```typescript\nfunction generateReadModel(rm: ReadModel): string {\n  const fields = rm.fields\n    .map(f => `  ${f.name}: ${mapType(f.type)}${f.optional ? ' | null' : ''};`)\n    .join('\\n');\n\n  return `export interface ${rm.name} {\\n${fields}\\n}`;\n}\n```\n\n### 4. Use Field Mappings for Projections\n\nThe `inboundDependencies` show how external events map to read model fields:\n\n```typescript\nfunction generateProjection(input: CodegenInput): string {\n  const rm = input.elements.readModels[0];\n  const handlers: string[] = [];\n\n  for (const dep of input.inboundDependencies) {\n    if (dep.target.name === rm.name) {\n      const mappings = dep.fieldMappings\n        .map(m => `    state.${m.targetFieldName} = event.${m.sourceFieldName};`)\n        .join('\\n');\n\n      handlers.push(`\n  on${dep.source.name}(state: ${rm.name}, event: ${dep.source.name}Event) {\n${mappings}\n  }`);\n    }\n  }\n\n  return `export class ${rm.name}Projection {\\n${handlers.join('\\n')}\\n}`;\n}\n```\n\n### 5. Generate Tests from Scenarios\n\nScenarios are BDD specs that become tests. There are two scenario patterns:\n\n**State-Change Scenarios** (whenCommand \u2192 then events/error):\n- `whenCommand`: The command being tested\n- `then.type: 'events'`: Expected events produced\n- `then.type: 'error'`: Expected error\n\n**Automation Scenarios** (whenEvents \u2192 then command):\n- `whenEvents`: The event(s) that trigger the processor\n- `then.type: 'command'`: The command the processor should issue\n\n```typescript\nfunction generateTests(input: CodegenInput): string {\n  return input.scenarios.map(scenario => {\n    const givenSetup = scenario.given\n      .map(g => `    await given(new ${g.eventName}(${JSON.stringify(g.fieldValues)}));`)\n      .join('\\n');\n\n    // State-change scenarios: when is a command\n    let whenAction = '';\n    if (scenario.whenCommand) {\n      whenAction = `    await when(new ${scenario.whenCommand.commandName}(${JSON.stringify(scenario.whenCommand.fieldValues)}));`;\n    }\n    // Automation scenarios: when is event(s)\n    if (scenario.whenEvents?.length > 0) {\n      whenAction = scenario.whenEvents\n        .map(e => `    await whenEvent(new ${e.eventName}(${JSON.stringify(e.fieldValues)}));`)\n        .join('\\n');\n    }\n\n    let thenAssertion: string;\n    if (scenario.then.type === 'events') {\n      const expected = scenario.then.expectedEvents!\n        .map(e => `new ${e.eventName}(${JSON.stringify(e.fieldValues)})`)\n        .join(', ');\n      thenAssertion = `    await thenExpect([${expected}]);`;\n    } else if (scenario.then.type === 'command') {\n      const cmd = scenario.then.expectedCommand!;\n      thenAssertion = `    await thenExpectCommand(new ${cmd.commandName}(${JSON.stringify(cmd.fieldValues)}));`;\n    } else if (scenario.then.type === 'error') {\n      thenAssertion = `    await thenExpectError('${scenario.then.errorType}', '${scenario.then.errorMessage}');`;\n    } else {\n      thenAssertion = `    await thenExpectState(${JSON.stringify(scenario.then.expectedFieldValues)});`;\n    }\n\n    return `\n  test('${scenario.name}', async () => {\n${givenSetup}\n${whenAction}\n${thenAssertion}\n  });`;\n  }).join('\\n');\n}\n```\n\n## Type Mapping\n\nMap event model types to your target language:\n\n```typescript\nfunction mapType(fieldType: string, isList?: boolean): string {\n  const baseType = {\n    'UUID': 'string',\n    'String': 'string',\n    'Int': 'number',\n    'Long': 'number',\n    'Double': 'number',\n    'Decimal': 'Decimal',  // or 'number' or 'BigNumber'\n    'Boolean': 'boolean',\n    'Date': 'Date',\n    'DateTime': 'Date',\n    'Custom': 'object',  // handle subfields separately\n  }[fieldType] ?? 'unknown';\n\n  return isList ? `${baseType}[]` : baseType;\n}\n```\n\nFor Custom types with subfields, generate inline or separate types:\n\n```typescript\nfunction generateFieldType(field: Field): string {\n  if (field.type === 'Custom' && field.subfields) {\n    const nested = field.subfields\n      .map(sf => `${sf.name}: ${mapType(sf.type)}`)\n      .join('; ');\n    const type = `{ ${nested} }`;\n    return field.list ? `Array<${type}>` : type;\n  }\n  return mapType(field.type, field.list);\n}\n```\n\n## Handling Aggregates\n\nEvents include their aggregate name when inside one:\n\n```typescript\nfunction generateEventHandler(input: CodegenInput): string {\n  const event = input.elements.events[0];\n  const aggregate = event.aggregate;\n\n  if (aggregate) {\n    return `\nexport class ${aggregate}Aggregate {\n  apply(event: ${event.name}Event) {\n    // Update aggregate state from event\n  }\n}`;\n  }\n  // ...\n}\n```\n\n## Running Your Generator\n\n```bash\n# Single slice\neventmodeler codegen slice \"Place Order\" | node generator.js\n\n# All slices (bash loop)\nfor slice in $(eventmodeler list slices --format json | node -e 'const fs=require(\"fs\");const d=JSON.parse(fs.readFileSync(0,\"utf8\"));for(const s of (d.slices||[])) console.log(s.name)'); do\n  eventmodeler codegen slice \"$slice\" | node generator.js\ndone\n\n# Chapter-scoped events scaffolding\neventmodeler codegen events --chapter \"Register Products\" | node generate-events.js\n\n# Whole-model events scaffolding\neventmodeler codegen events | node generate-events.js\n```\n\n## Best Practices\n\n1. **Handle all slice types** - Your generator should handle STATE_CHANGE, STATE_VIEW, and AUTOMATION\n2. **Use field mappings** - They define the projection logic between events and read models\n3. **Generate tests from scenarios** - Scenarios are executable specifications\n4. **Respect field attributes** - `generated` fields don't need input, `optional` fields can be null\n5. **Use aggregate info** - Events in aggregates should be handled by that aggregate\n6. **Handle Custom types recursively** - Subfields can themselves be Custom types\n7. **Make it idempotent** - Running twice should produce the same output\n";

package/dist/slices/guide/guides/codegen.js

@@ -0,0 +1,339 @@
+export const meta = {
+    name: 'codegen',
+    description: 'Build code generators that consume eventmodeler codegen output',
+};
+export const content = `
+# Building Code Generators for Event Models
+
+The \`eventmodeler codegen\` commands output structured JSON that code generators can consume:
+- \`eventmodeler codegen slice "<slice-name>"\` for per-slice generation
+- \`eventmodeler codegen events [--chapter "<chapter-name>"]\` for deduplicated event scaffolding across slices
+
+## The Codegen Pipeline
+
+Per-slice pipeline:
+
+\`\`\`
+eventmodeler codegen slice "Place Order" | your-generator > output-files
+\`\`\`
+
+Events-only pipeline:
+
+\`\`\`
+eventmodeler codegen events --chapter "Register Products" | your-events-generator > events.kt
+\`\`\`
+
+Your generator receives JSON on stdin and produces code files.
+
+## Understanding the Input
+
+Run codegen to see what you'll receive:
+
+\`\`\`bash
+eventmodeler codegen slice "Place Order"
+\`\`\`
+
+### Top-Level Structure
+
+\`\`\`json
+{
+  "sliceType": "STATE_CHANGE | STATE_VIEW | AUTOMATION",
+  "slice": { "id": "...", "name": "Place Order" },
+  "chapter": { "name": "...", "hierarchy": ["Parent", "Child"] },
+  "elements": { ... },
+  "inboundDependencies": [ ... ],
+  "internalFlows": [ ... ],
+  "scenarios": [ ... ]
+}
+\`\`\`
+
+### Events-Only Structure (\`codegen events\`)
+
+\`\`\`json
+{
+  "chapter": { "name": "Register Products", "parent": { "name": "Configuration" } },
+  "sliceCount": 4,
+  "eventCount": 9,
+  "slices": [
+    { "id": "...", "name": "Place Product", "sliceType": "STATE_CHANGE" }
+  ],
+  "events": [
+    {
+      "id": "...",
+      "name": "ProductRegistered",
+      "fields": [ ... ],
+      "aggregate": "Product",
+      "sourceSlices": ["Place Product", "Import Product"]
+    }
+  ]
+}
+\`\`\`
+
+Use \`codegen events\` when generating shared event artifacts in one pass (for a chapter or entire model).
+
+### Slice Types and What to Generate
+
+| sliceType | Components | Generate |
+|-----------|------------|----------|
+| \`STATE_CHANGE\` | Screen, Command, Event | API endpoint, command handler, event, tests |
+| \`STATE_VIEW\` | ReadModel | Projection/denormalizer, query endpoint |
+| \`AUTOMATION\` | Processor, ReadModel, Command, Event | Event handler, saga/process manager |
+
+## Building a Generator: Step by Step
+
+### 1. Parse the Input
+
+\`\`\`typescript
+// generator.ts
+import { stdin } from 'process';
+
+interface CodegenInput {
+  sliceType: 'STATE_CHANGE' | 'STATE_VIEW' | 'AUTOMATION';
+  slice: { id: string; name: string };
+  elements: {
+    commands: Array<{ name: string; fields: Field[] }>;
+    events: Array<{ name: string; fields: Field[]; aggregate?: string }>;
+    readModels: Array<{ name: string; fields: Field[] }>;
+    screens: Array<{ name: string; fields: Field[] }>;
+    processors: Array<{ name: string }>;
+  };
+  inboundDependencies: InboundDependency[];
+  internalFlows: Flow[];
+  scenarios: Scenario[];
+}
+
+async function readInput(): Promise<CodegenInput> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of stdin) {
+    chunks.push(chunk);
+  }
+  return JSON.parse(Buffer.concat(chunks).toString());
+}
+\`\`\`
+
+### 2. Route by Slice Type
+
+\`\`\`typescript
+async function main() {
+  const input = await readInput();
+
+  switch (input.sliceType) {
+    case 'STATE_CHANGE':
+      generateStateChangeSlice(input);
+      break;
+    case 'STATE_VIEW':
+      generateStateViewSlice(input);
+      break;
+    case 'AUTOMATION':
+      generateAutomationSlice(input);
+      break;
+  }
+}
+\`\`\`
+
+### 3. Generate from Elements
+
+**Commands → DTOs/Request types:**
+\`\`\`typescript
+function generateCommand(cmd: Command): string {
+  const fields = cmd.fields
+    .map(f => \`  \${f.name}: \${mapType(f.type)}\${f.optional ? ' | null' : ''};\`)
+    .join('\\n');
+
+  return \`export interface \${cmd.name}Command {\\n\${fields}\\n}\`;
+}
+\`\`\`
+
+**Events → Event types with metadata:**
+\`\`\`typescript
+function generateEvent(evt: Event): string {
+  const fields = evt.fields.map(f => {
+    const generated = f.generated ? ' // generated' : '';
+    return \`  \${f.name}: \${mapType(f.type)};\${generated}\`;
+  }).join('\\n');
+
+  return \`export interface \${evt.name}Event {\\n  type: '\${evt.name}';\\n\${fields}\\n}\`;
+}
+\`\`\`
+
+**ReadModels → Projection types:**
+\`\`\`typescript
+function generateReadModel(rm: ReadModel): string {
+  const fields = rm.fields
+    .map(f => \`  \${f.name}: \${mapType(f.type)}\${f.optional ? ' | null' : ''};\`)
+    .join('\\n');
+
+  return \`export interface \${rm.name} {\\n\${fields}\\n}\`;
+}
+\`\`\`
+
+### 4. Use Field Mappings for Projections
+
+The \`inboundDependencies\` show how external events map to read model fields:
+
+\`\`\`typescript
+function generateProjection(input: CodegenInput): string {
+  const rm = input.elements.readModels[0];
+  const handlers: string[] = [];
+
+  for (const dep of input.inboundDependencies) {
+    if (dep.target.name === rm.name) {
+      const mappings = dep.fieldMappings
+        .map(m => \`    state.\${m.targetFieldName} = event.\${m.sourceFieldName};\`)
+        .join('\\n');
+
+      handlers.push(\`
+  on\${dep.source.name}(state: \${rm.name}, event: \${dep.source.name}Event) {
+\${mappings}
+  }\`);
+    }
+  }
+
+  return \`export class \${rm.name}Projection {\\n\${handlers.join('\\n')}\\n}\`;
+}
+\`\`\`
+
+### 5. Generate Tests from Scenarios
+
+Scenarios are BDD specs that become tests. There are two scenario patterns:
+
+**State-Change Scenarios** (whenCommand → then events/error):
+- \`whenCommand\`: The command being tested
+- \`then.type: 'events'\`: Expected events produced
+- \`then.type: 'error'\`: Expected error
+
+**Automation Scenarios** (whenEvents → then command):
+- \`whenEvents\`: The event(s) that trigger the processor
+- \`then.type: 'command'\`: The command the processor should issue
+
+\`\`\`typescript
+function generateTests(input: CodegenInput): string {
+  return input.scenarios.map(scenario => {
+    const givenSetup = scenario.given
+      .map(g => \`    await given(new \${g.eventName}(\${JSON.stringify(g.fieldValues)}));\`)
+      .join('\\n');
+
+    // State-change scenarios: when is a command
+    let whenAction = '';
+    if (scenario.whenCommand) {
+      whenAction = \`    await when(new \${scenario.whenCommand.commandName}(\${JSON.stringify(scenario.whenCommand.fieldValues)}));\`;
+    }
+    // Automation scenarios: when is event(s)
+    if (scenario.whenEvents?.length > 0) {
+      whenAction = scenario.whenEvents
+        .map(e => \`    await whenEvent(new \${e.eventName}(\${JSON.stringify(e.fieldValues)}));\`)
+        .join('\\n');
+    }
+
+    let thenAssertion: string;
+    if (scenario.then.type === 'events') {
+      const expected = scenario.then.expectedEvents!
+        .map(e => \`new \${e.eventName}(\${JSON.stringify(e.fieldValues)})\`)
+        .join(', ');
+      thenAssertion = \`    await thenExpect([\${expected}]);\`;
+    } else if (scenario.then.type === 'command') {
+      const cmd = scenario.then.expectedCommand!;
+      thenAssertion = \`    await thenExpectCommand(new \${cmd.commandName}(\${JSON.stringify(cmd.fieldValues)}));\`;
+    } else if (scenario.then.type === 'error') {
+      thenAssertion = \`    await thenExpectError('\${scenario.then.errorType}', '\${scenario.then.errorMessage}');\`;
+    } else {
+      thenAssertion = \`    await thenExpectState(\${JSON.stringify(scenario.then.expectedFieldValues)});\`;
+    }
+
+    return \`
+  test('\${scenario.name}', async () => {
+\${givenSetup}
+\${whenAction}
+\${thenAssertion}
+  });\`;
+  }).join('\\n');
+}
+\`\`\`
+
+## Type Mapping
+
+Map event model types to your target language:
+
+\`\`\`typescript
+function mapType(fieldType: string, isList?: boolean): string {
+  const baseType = {
+    'UUID': 'string',
+    'String': 'string',
+    'Int': 'number',
+    'Long': 'number',
+    'Double': 'number',
+    'Decimal': 'Decimal',  // or 'number' or 'BigNumber'
+    'Boolean': 'boolean',
+    'Date': 'Date',
+    'DateTime': 'Date',
+    'Custom': 'object',  // handle subfields separately
+  }[fieldType] ?? 'unknown';
+
+  return isList ? \`\${baseType}[]\` : baseType;
+}
+\`\`\`
+
+For Custom types with subfields, generate inline or separate types:
+
+\`\`\`typescript
+function generateFieldType(field: Field): string {
+  if (field.type === 'Custom' && field.subfields) {
+    const nested = field.subfields
+      .map(sf => \`\${sf.name}: \${mapType(sf.type)}\`)
+      .join('; ');
+    const type = \`{ \${nested} }\`;
+    return field.list ? \`Array<\${type}>\` : type;
+  }
+  return mapType(field.type, field.list);
+}
+\`\`\`
+
+## Handling Aggregates
+
+Events include their aggregate name when inside one:
+
+\`\`\`typescript
+function generateEventHandler(input: CodegenInput): string {
+  const event = input.elements.events[0];
+  const aggregate = event.aggregate;
+
+  if (aggregate) {
+    return \`
+export class \${aggregate}Aggregate {
+  apply(event: \${event.name}Event) {
+    // Update aggregate state from event
+  }
+}\`;
+  }
+  // ...
+}
+\`\`\`
+
+## Running Your Generator
+
+\`\`\`bash
+# Single slice
+eventmodeler codegen slice "Place Order" | node generator.js
+
+# All slices (bash loop)
+for slice in $(eventmodeler list slices --format json | node -e 'const fs=require("fs");const d=JSON.parse(fs.readFileSync(0,"utf8"));for(const s of (d.slices||[])) console.log(s.name)'); do
+  eventmodeler codegen slice "$slice" | node generator.js
+done
+
+# Chapter-scoped events scaffolding
+eventmodeler codegen events --chapter "Register Products" | node generate-events.js
+
+# Whole-model events scaffolding
+eventmodeler codegen events | node generate-events.js
+\`\`\`
+
+## Best Practices
+
+1. **Handle all slice types** - Your generator should handle STATE_CHANGE, STATE_VIEW, and AUTOMATION
+2. **Use field mappings** - They define the projection logic between events and read models
+3. **Generate tests from scenarios** - Scenarios are executable specifications
+4. **Respect field attributes** - \`generated\` fields don't need input, \`optional\` fields can be null
+5. **Use aggregate info** - Events in aggregates should be handled by that aggregate
+6. **Handle Custom types recursively** - Subfields can themselves be Custom types
+7. **Make it idempotent** - Running twice should produce the same output
+`;

package/dist/slices/guide/guides/connect-slices.d.ts

@@ -0,0 +1,5 @@
+export declare const meta: {
+    name: string;
+    description: string;
+};
+export declare const content = "\n# Connecting Slices\n\nAfter creating slices, you need to connect them with flows to show how data moves through the system. This creates the complete picture of your event model.\n\n## The Data Flow Pattern\n\nIn event modeling, data flows in a specific pattern:\n\n```\n[State-Change Slice]              [State-View Slice]              [Next Slice]\n\n     Screen                            ReadModel                     Screen\n       |                                  ^  |                         ^\n       v                                  |  v                         |\n    Command                               |  - - - - - - - - - - - - - +\n       |                                  |                    OR\n       v                                  |                   Processor\n     Event  - - - - - - - - - - - - - - - +                      ^\n                                                                 |\n                                          + - - - - - - - - - - -+\n```\n\n**Key flows:**\n1. **Event \u2192 ReadModel**: Events project their data into read models\n2. **ReadModel \u2192 Screen**: Read models provide data to screens (for user viewing)\n3. **ReadModel \u2192 Processor**: Read models provide data to processors (for automation)\n\nWithin-slice flows (Screen\u2192Command, Command\u2192Event, Processor\u2192Command) are created automatically when you create a slice.\n\n## Command Syntax\n\n```bash\neventmodeler create flow --from \"<source>\" --to \"<target>\"\n```\n\n## Valid Flow Combinations\n\n| Source | Target | Use Case |\n|--------|--------|----------|\n| Event | ReadModel | Project event data into a view |\n| ReadModel | Screen | Provide data for user display |\n| ReadModel | Processor | Provide data for automation logic |\n\n## Workflow: Connecting a Complete Model\n\n### 1. Create Your Slices First\n\n```bash\n# User places an order\neventmodeler create state-change-slice --xml '<state-change-slice name=\"Place Order\">\n  <screen name=\"Checkout\">...</screen>\n  <command name=\"PlaceOrder\">...</command>\n  <event name=\"OrderPlaced\">...</event>\n</state-change-slice>'\n\n# View for order status\neventmodeler create state-view-slice --xml '<state-view-slice name=\"View Order Status\" after=\"Place Order\">\n  <read-model name=\"OrderStatus\">...</read-model>\n</state-view-slice>'\n\n# System automatically fulfills order (includes its own read model)\neventmodeler create automation-slice --xml '<automation-slice name=\"Auto Fulfill\" after=\"View Order Status\">\n  <read-model name=\"OrderReadyToFulfill\">\n    <field name=\"orderId\" type=\"UUID\"/>\n    <field name=\"isPaid\" type=\"Boolean\"/>\n  </read-model>\n  <processor name=\"Fulfillment Processor\"/>\n  <command name=\"FulfillOrder\">...</command>\n  <event name=\"OrderFulfilled\">...</event>\n</automation-slice>'\n```\n\n### 2. Connect Events to Read Models\n\nEvents project their data into read models:\n\n```bash\n# OrderPlaced feeds into OrderStatus view\neventmodeler create flow --from \"OrderPlaced\" --to \"OrderStatus\"\n\n# OrderFulfilled also updates OrderStatus view\neventmodeler create flow --from \"OrderFulfilled\" --to \"OrderStatus\"\n```\n\n### 3. Connect Events to Automation Read Models\n\nAutomation slices have their own internal read model. Connect external events to feed it:\n\n```bash\n# OrderPlaced feeds the automation's read model\neventmodeler create flow --from \"OrderPlaced\" --to \"OrderReadyToFulfill\"\n\n# PaymentReceived also feeds the automation's read model\neventmodeler create flow --from \"PaymentReceived\" --to \"OrderReadyToFulfill\"\n```\n\nNote: The flow from ReadModel \u2192 Processor is internal to the automation slice and created automatically.\n\n### 4. Connect Read Models to Screens\n\nState-view read models provide data to screens:\n\n```bash\n# OrderStatus provides data to a screen in another slice\neventmodeler create flow --from \"OrderStatus\" --to \"Order Details Screen\"\n```\n\n### 5. Set Up Field Mappings\n\nAfter creating flows, map the fields:\n\n```bash\neventmodeler map fields --flow \"OrderPlaced\u2192OrderStatus\" --xml '\n  <mapping from=\"orderId\" to=\"orderId\"/>\n  <mapping from=\"customerId\" to=\"customerId\"/>\n  <mapping from=\"placedAt\" to=\"placedAt\"/>\n'\n```\n\n### 6. Verify Completeness\n\nCheck that all flows have proper field mappings:\n\n```bash\neventmodeler show model-completeness\neventmodeler show completeness \"OrderStatus\"\n```\n\n## Handling Duplicate Names with IDs\n\nWhen multiple elements share the same name (e.g., linked copies of events or read models), you'll need to use element IDs instead of names.\n\n### Finding Element IDs\n\n```bash\n# List events with their IDs\neventmodeler list events\n# Output:\n# <events>\n#   <event id=\"abc12345-...\" name=\"OrderPlaced\" fields=\"4\"/>\n#   <event id=\"def67890-...\" name=\"OrderPlaced\" fields=\"4\"/>  <!-- linked copy -->\n# </events>\n```\n\n### Using IDs in Commands\n\nPrefix the ID (or ID prefix) with `id:`:\n\n```bash\n# Create flow using ID prefix (first 8 characters is usually enough)\neventmodeler create flow --from \"id:abc12345\" --to \"OrderStatus\"\n\n# Map fields using ID prefix\neventmodeler map fields --flow \"id:abc12345\u2192OrderStatus\" --xml '\n  <mapping from=\"orderId\" to=\"orderId\"/>\n'\n```\n\n### When the CLI Finds Duplicates\n\nIf you use a name that matches multiple elements, the CLI will show you the options:\n\n```bash\neventmodeler create flow --from \"OrderPlaced\" --to \"OrderStatus\"\n# Error: Multiple events found with name \"OrderPlaced\"\n# Please specify using the element ID:\n#   - \"OrderPlaced\" (id: abc12345-1234-5678-9abc-def012345678)\n#   - \"OrderPlaced\" (id: def67890-1234-5678-9abc-def012345678)\n#\n# Usage: eventmodeler create flow --from \"id:abc12345\" --to \"OrderStatus\"\n```\n\n## Common Patterns\n\n### Pattern 1: Event Sourced View\nMultiple events feed into one read model:\n\n```bash\neventmodeler create flow --from \"OrderPlaced\" --to \"OrderSummary\"\neventmodeler create flow --from \"OrderShipped\" --to \"OrderSummary\"\neventmodeler create flow --from \"OrderDelivered\" --to \"OrderSummary\"\n```\n\n### Pattern 2: Automation Triggered by Events\nEvents feed an automation slice's internal read model:\n\n```bash\neventmodeler create flow --from \"OrderPlaced\" --to \"OrderReadyForShipment\"\neventmodeler create flow --from \"PaymentReceived\" --to \"OrderReadyForShipment\"\n```\n\n### Pattern 3: User Dashboard\nA read model feeds a screen for user viewing:\n\n```bash\neventmodeler create flow --from \"UserDashboard\" --to \"Dashboard Screen\"\n```\n\n## Error Handling\n\nThe CLI prevents invalid flows:\n\n```bash\n# This will error - can't go directly from Event to Screen\neventmodeler create flow --from \"OrderPlaced\" --to \"Checkout Screen\"\n# Error: Cannot create flow directly from Event to Screen.\n# Events flow to ReadModels, which then flow to Screens.\n\n# This will error - can't go from ReadModel to ReadModel\neventmodeler create flow --from \"OrderStatus\" --to \"CustomerProfile\"\n# Error: Cannot create flow from ReadModel to ReadModel.\n```\n\n## Best Practices\n\n1. **Create all slices first** - Easier to see the full picture before connecting\n2. **Connect events to read models** - Every event should feed at least one read model\n3. **Think about what triggers what** - Automation slices need data from read models\n4. **Map fields after creating flows** - Use `map fields` to complete the data flow\n5. **Verify completeness** - Run `show model-completeness` to find missing mappings\n6. **Use IDs for duplicates** - When names aren't unique, use `id:` prefix with element IDs\n";