eventmodeler 0.4.6 → 0.5.0

package/dist/slices/guide/guides/connect-slices.js

@@ -0,0 +1,202 @@
+export const meta = {
+    name: 'connect-slices',
+    description: 'Connect slices with flows to show how data moves through the system',
+};
+export const content = `
+# Connecting Slices
+
+After 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.
+
+## The Data Flow Pattern
+
+In event modeling, data flows in a specific pattern:
+
+\`\`\`
+[State-Change Slice]              [State-View Slice]              [Next Slice]
+
+     Screen                            ReadModel                     Screen
+       |                                  ^  |                         ^
+       v                                  |  v                         |
+    Command                               |  - - - - - - - - - - - - - +
+       |                                  |                    OR
+       v                                  |                   Processor
+     Event  - - - - - - - - - - - - - - - +                      ^
+                                                                 |
+                                          + - - - - - - - - - - -+
+\`\`\`
+
+**Key flows:**
+1. **Event → ReadModel**: Events project their data into read models
+2. **ReadModel → Screen**: Read models provide data to screens (for user viewing)
+3. **ReadModel → Processor**: Read models provide data to processors (for automation)
+
+Within-slice flows (Screen→Command, Command→Event, Processor→Command) are created automatically when you create a slice.
+
+## Command Syntax
+
+\`\`\`bash
+eventmodeler create flow --from "<source>" --to "<target>"
+\`\`\`
+
+## Valid Flow Combinations
+
+| Source | Target | Use Case |
+|--------|--------|----------|
+| Event | ReadModel | Project event data into a view |
+| ReadModel | Screen | Provide data for user display |
+| ReadModel | Processor | Provide data for automation logic |
+
+## Workflow: Connecting a Complete Model
+
+### 1. Create Your Slices First
+
+\`\`\`bash
+# User places an order
+eventmodeler create state-change-slice --xml '<state-change-slice name="Place Order">
+  <screen name="Checkout">...</screen>
+  <command name="PlaceOrder">...</command>
+  <event name="OrderPlaced">...</event>
+</state-change-slice>'
+
+# View for order status
+eventmodeler create state-view-slice --xml '<state-view-slice name="View Order Status" after="Place Order">
+  <read-model name="OrderStatus">...</read-model>
+</state-view-slice>'
+
+# System automatically fulfills order (includes its own read model)
+eventmodeler create automation-slice --xml '<automation-slice name="Auto Fulfill" after="View Order Status">
+  <read-model name="OrderReadyToFulfill">
+    <field name="orderId" type="UUID"/>
+    <field name="isPaid" type="Boolean"/>
+  </read-model>
+  <processor name="Fulfillment Processor"/>
+  <command name="FulfillOrder">...</command>
+  <event name="OrderFulfilled">...</event>
+</automation-slice>'
+\`\`\`
+
+### 2. Connect Events to Read Models
+
+Events project their data into read models:
+
+\`\`\`bash
+# OrderPlaced feeds into OrderStatus view
+eventmodeler create flow --from "OrderPlaced" --to "OrderStatus"
+
+# OrderFulfilled also updates OrderStatus view
+eventmodeler create flow --from "OrderFulfilled" --to "OrderStatus"
+\`\`\`
+
+### 3. Connect Events to Automation Read Models
+
+Automation slices have their own internal read model. Connect external events to feed it:
+
+\`\`\`bash
+# OrderPlaced feeds the automation's read model
+eventmodeler create flow --from "OrderPlaced" --to "OrderReadyToFulfill"
+
+# PaymentReceived also feeds the automation's read model
+eventmodeler create flow --from "PaymentReceived" --to "OrderReadyToFulfill"
+\`\`\`
+
+Note: The flow from ReadModel → Processor is internal to the automation slice and created automatically.
+
+### 4. Connect Read Models to Screens
+
+State-view read models provide data to screens:
+
+\`\`\`bash
+# OrderStatus provides data to a screen in another slice
+eventmodeler create flow --from "OrderStatus" --to "Order Details Screen"
+\`\`\`
+
+### 5. Set Up Field Mappings
+
+After creating flows, map the fields:
+
+\`\`\`bash
+eventmodeler map fields --flow "OrderPlaced→OrderStatus" --xml '
+  <mapping from="orderId" to="orderId"/>
+  <mapping from="customerId" to="customerId"/>
+  <mapping from="placedAt" to="placedAt"/>
+'
+\`\`\`
+
+### 6. Verify Completeness
+
+Check that all flows have proper field mappings:
+
+\`\`\`bash
+eventmodeler show model-completeness
+eventmodeler show completeness "OrderStatus"
+\`\`\`
+
+## Handling Duplicate Names with IDs
+
+When multiple elements share the same name (e.g., linked copies of events or read models), use element IDs with the \`id:\` prefix. This works with every command that accepts an element name — not just flows. See \`eventmodeler guide explore\` for the full details.
+
+\`\`\`bash
+# Find element IDs via list commands
+eventmodeler list events
+# <event id="abc12345-..." name="OrderPlaced" fields="4"/>
+# <event id="def67890-..." name="OrderPlaced" fields="4"/>  <!-- linked copy -->
+
+# Use ID prefix (first 8 chars is usually enough)
+eventmodeler create flow --from "id:abc12345" --to "OrderStatus"
+eventmodeler map fields --flow "id:abc12345→OrderStatus" --xml '
+  <mapping from="orderId" to="orderId"/>
+'
+\`\`\`
+
+The CLI will tell you when names are ambiguous and show the IDs to choose from.
+
+## Common Patterns
+
+### Pattern 1: Event Sourced View
+Multiple events feed into one read model:
+
+\`\`\`bash
+eventmodeler create flow --from "OrderPlaced" --to "OrderSummary"
+eventmodeler create flow --from "OrderShipped" --to "OrderSummary"
+eventmodeler create flow --from "OrderDelivered" --to "OrderSummary"
+\`\`\`
+
+### Pattern 2: Automation Triggered by Events
+Events feed an automation slice's internal read model:
+
+\`\`\`bash
+eventmodeler create flow --from "OrderPlaced" --to "OrderReadyForShipment"
+eventmodeler create flow --from "PaymentReceived" --to "OrderReadyForShipment"
+\`\`\`
+
+### Pattern 3: User Dashboard
+A read model feeds a screen for user viewing:
+
+\`\`\`bash
+eventmodeler create flow --from "UserDashboard" --to "Dashboard Screen"
+\`\`\`
+
+## Error Handling
+
+The CLI prevents invalid flows:
+
+\`\`\`bash
+# This will error - can't go directly from Event to Screen
+eventmodeler create flow --from "OrderPlaced" --to "Checkout Screen"
+# Error: Cannot create flow directly from Event to Screen.
+# Events flow to ReadModels, which then flow to Screens.
+
+# This will error - can't go from ReadModel to ReadModel
+eventmodeler create flow --from "OrderStatus" --to "CustomerProfile"
+# Error: Cannot create flow from ReadModel to ReadModel.
+\`\`\`
+
+## Best Practices
+
+1. **Create all slices first** - Easier to see the full picture before connecting
+2. **Connect events to read models** - Every event should feed at least one read model
+3. **Think about what triggers what** - Automation slices need data from read models
+4. **Map fields after creating flows** - Use \`map fields\` to complete the data flow
+5. **Verify completeness** - Run \`show model-completeness\` to find missing mappings
+6. **Use IDs for duplicates** - When names aren't unique, use \`id:\` prefix with element IDs
+`;

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

@@ -0,0 +1,5 @@
+export declare const meta: {
+    name: string;
+    description: string;
+};
+export declare const content = "\n# Creating Slices\n\nThere are three slice types in an event model. Each represents a different pattern of data flow.\n\n---\n\n## State-Change Slices\n\nA state-change slice represents a **user-initiated action** that changes system state:\n\n```\nScreen \u2192 Command \u2192 Event\n```\n\n- **Screen**: The UI where the user initiates the action\n- **Command**: The intent/request to change state\n- **Event**: The fact that state changed\n\n### When to Use\n\nUse state-change slices when:\n- A user performs an action (clicks a button, submits a form)\n- That action changes the state of an entity\n- Examples: \"Place Order\", \"Cancel Subscription\", \"Update Profile\", \"Add Item to Cart\"\n\n### Command Syntax\n\n```bash\neventmodeler create state-change-slice --xml '<state-change-slice name=\"Slice Name\" [after=\"Other Slice\"]>\n  <screen name=\"Screen Name\">\n    <field name=\"fieldName\" type=\"Type\"/>\n  </screen>\n  <command name=\"CommandName\">\n    <field name=\"fieldName\" type=\"Type\"/>\n  </command>\n  <event name=\"EventName\">\n    <field name=\"fieldName\" type=\"Type\"/>\n  </event>\n</state-change-slice>'\n```\n\n### Example: Place Order Slice\n\n```bash\neventmodeler create state-change-slice --xml '<state-change-slice name=\"Place Order\">\n  <screen name=\"Checkout Screen\">\n    <field name=\"customerId\" type=\"UUID\"/>\n    <field name=\"items\" type=\"String\" isUserInput=\"true\"/>\n    <field name=\"shippingAddress\" type=\"String\" isUserInput=\"true\"/>\n  </screen>\n  <command name=\"PlaceOrder\">\n    <field name=\"customerId\" type=\"UUID\"/>\n    <field name=\"items\" type=\"String\"/>\n    <field name=\"shippingAddress\" type=\"String\"/>\n  </command>\n  <event name=\"OrderPlaced\">\n    <field name=\"orderId\" type=\"UUID\" isGenerated=\"true\"/>\n    <field name=\"customerId\" type=\"UUID\"/>\n    <field name=\"items\" type=\"String\"/>\n    <field name=\"shippingAddress\" type=\"String\"/>\n    <field name=\"placedAt\" type=\"DateTime\" isGenerated=\"true\"/>\n  </event>\n</state-change-slice>'\n```\n\n### Automatic Behavior\n\n1. **Positioning**: Places slice at end, or use `after=\"Slice Name\"` or `before=\"Slice Name\"`\n2. **Field mappings**: Automatically inferred by matching field names between Screen \u2192 Command and Command \u2192 Event\n3. **Flows**: Automatically creates Screen\u2192Command and Command\u2192Event flows\n\n---\n\n## Automation Slices\n\nAn automation slice represents a **system-initiated action**:\n\n```\nReadModel \u2192 Processor \u2192 Command \u2192 Event\n```\n\n- **ReadModel**: The state/data the processor needs to make decisions\n- **Processor**: The system component that decides when and how to act\n- **Command**: The intent/request to change state\n- **Event**: The fact that state changed\n\n### When to Use\n\nUse automation slices when:\n- The system automatically responds to events\n- No direct user interaction triggers the action\n- Examples: \"Auto-assign Reviewer\", \"Send Reminder Email\", \"Calculate Shipping\", \"Process Payment\"\n\n### Command Syntax\n\n```bash\neventmodeler create automation-slice --xml '<automation-slice name=\"Slice Name\" [after=\"Other Slice\"]>\n  <read-model name=\"ReadModelName\">\n    <field name=\"fieldName\" type=\"Type\"/>\n  </read-model>\n  <processor name=\"Processor Name\"/>\n  <command name=\"CommandName\">\n    <field name=\"fieldName\" type=\"Type\"/>\n  </command>\n  <event name=\"EventName\">\n    <field name=\"fieldName\" type=\"Type\"/>\n  </event>\n</automation-slice>'\n```\n\n### Example: Auto-Fulfill Order\n\n```bash\neventmodeler create automation-slice --xml '<automation-slice name=\"Auto Fulfill Order\" after=\"Place Order\">\n  <read-model name=\"OrderReadyForFulfillment\">\n    <field name=\"orderId\" type=\"UUID\"/>\n    <field name=\"isPaid\" type=\"Boolean\"/>\n    <field name=\"shippingAddress\" type=\"String\"/>\n  </read-model>\n  <processor name=\"Order Fulfillment Processor\"/>\n  <command name=\"FulfillOrder\">\n    <field name=\"orderId\" type=\"UUID\"/>\n    <field name=\"warehouseId\" type=\"UUID\" isGenerated=\"true\"/>\n  </command>\n  <event name=\"OrderFulfilled\">\n    <field name=\"orderId\" type=\"UUID\"/>\n    <field name=\"warehouseId\" type=\"UUID\"/>\n    <field name=\"fulfilledAt\" type=\"DateTime\" isGenerated=\"true\"/>\n  </event>\n</automation-slice>'\n```\n\n### Automatic Behavior\n\n1. **Positioning**: Places slice at end, or use `after=\"Slice Name\"` or `before=\"Slice Name\"`\n2. **Field mappings**: Automatically inferred by matching field names: ReadModel \u2192 Command, Command \u2192 Event\n3. **Flows**: Automatically creates ReadModel \u2192 Processor, Processor \u2192 Command, Command \u2192 Event\n\n### Connecting Trigger Events\n\nAfter creating the automation slice, connect external events to its read model:\n\n```bash\neventmodeler create flow --from \"OrderPlaced\" --to \"OrderReadyForFulfillment\"\neventmodeler create flow --from \"PaymentReceived\" --to \"OrderReadyForFulfillment\"\n```\n\n### Automation vs State-View Read Models\n\n| Automation ReadModel | State-View ReadModel |\n|---------------------|---------------------|\n| Inside automation slice | Standalone slice |\n| Feeds a Processor | Feeds a Screen |\n| \"What the processor needs\" | \"What the user sees\" |\n| Created with automation-slice | Created with state-view-slice |\n\n---\n\n## State-View Slices\n\nA state-view slice represents a **read model** - a projection of event data for querying:\n\n```\nRead Model (fed by events)\n```\n\n### When to Use\n\nUse state-view slices when:\n- You need to display data to users\n- A processor needs to query current state\n- You want to aggregate data from multiple events\n- Examples: \"Order Summary\", \"User Dashboard\", \"Inventory Levels\", \"Account Balance\"\n\n### Command Syntax\n\n```bash\neventmodeler create state-view-slice --xml '<state-view-slice name=\"Slice Name\" [after=\"Other Slice\"]>\n  <read-model name=\"ReadModelName\">\n    <field name=\"fieldName\" type=\"Type\"/>\n  </read-model>\n</state-view-slice>'\n```\n\n### Example: Order Summary View\n\n```bash\neventmodeler create state-view-slice --xml '<state-view-slice name=\"View Order Summary\" after=\"Place Order\">\n  <read-model name=\"OrderSummary\">\n    <field name=\"orderId\" type=\"UUID\"/>\n    <field name=\"customerId\" type=\"UUID\"/>\n    <field name=\"customerName\" type=\"String\"/>\n    <field name=\"status\" type=\"String\"/>\n    <field name=\"totalAmount\" type=\"Decimal\"/>\n    <field name=\"itemCount\" type=\"Int\"/>\n    <field name=\"placedAt\" type=\"DateTime\"/>\n    <field name=\"lastUpdatedAt\" type=\"DateTime\"/>\n  </read-model>\n</state-view-slice>'\n```\n\n### Connecting Events After Creation\n\nThe `create state-view-slice` command only creates the read model. To complete the picture:\n\n1. Create flows from events: `eventmodeler create flow --from \"EventName\" --to \"ReadModelName\"`\n2. Map fields: `eventmodeler map fields --flow \"EventName\u2192ReadModelName\" --xml '...'`\n3. Verify: `eventmodeler show completeness \"ReadModelName\"`\n\n---\n\n## Field Types\n\n`UUID`, `String`, `Int`, `Long`, `Double`, `Decimal`, `Boolean`, `Date`, `DateTime`, `Custom`\n\n## Field Attributes\n\n- `isOptional=\"true\"` - Field may not have a value\n- `isGenerated=\"true\"` - System-generated (e.g., IDs, timestamps), not from user input\n- `isUserInput=\"true\"` - Entered by the user on the screen\n- `isList=\"true\"` - Field is a list/array of the specified type\n\n## Working with Lists and Custom Types\n\n**List of primitives** - use `isList=\"true\"` with any valid type:\n```xml\n<field name=\"tags\" type=\"String\" isList=\"true\"/>\n<field name=\"quantities\" type=\"Int\" isList=\"true\"/>\n```\n\n### Custom Types (Nested Objects)\n\n**CRITICAL: Custom fields MUST contain subfields.** The `type=\"Custom\"` indicates a nested object structure, and the nested `<field>` elements define its properties. A Custom field without subfields is invalid and creates an empty, useless type.\n\n**Custom type with nested fields:**\n```xml\n<field name=\"address\" type=\"Custom\">\n  <field name=\"street\" type=\"String\"/>\n  <field name=\"city\" type=\"String\"/>\n  <field name=\"postalCode\" type=\"String\"/>\n</field>\n```\n\n**List of custom objects** - combine `type=\"Custom\"` with `isList=\"true\"`:\n```xml\n<field name=\"lineItems\" type=\"Custom\" isList=\"true\">\n  <field name=\"productId\" type=\"UUID\"/>\n  <field name=\"quantity\" type=\"Int\"/>\n  <field name=\"unitPrice\" type=\"Decimal\"/>\n</field>\n```\n\n**Nested custom types** - subfields can themselves be Custom types:\n```xml\n<field name=\"customer\" type=\"Custom\">\n  <field name=\"customerId\" type=\"UUID\"/>\n  <field name=\"name\" type=\"String\"/>\n  <field name=\"billingAddress\" type=\"Custom\">\n    <field name=\"street\" type=\"String\"/>\n    <field name=\"city\" type=\"String\"/>\n    <field name=\"country\" type=\"String\"/>\n  </field>\n</field>\n```\n\n## Common Mistakes\n\n- **Creating empty Custom fields**: Custom fields MUST have subfields that define their structure.\n  - Wrong: `<field name=\"address\" type=\"Custom\"/>`\n  - Right: `<field name=\"address\" type=\"Custom\"><field name=\"street\" type=\"String\"/>...</field>`\n\n- **Using \"List\" as a field type**: \"List\" is not a valid type. Use `isList=\"true\"` with a valid type instead.\n  - Wrong: `<field name=\"items\" type=\"List\"/>`\n  - Right: `<field name=\"items\" type=\"String\" isList=\"true\"/>`\n\n- **Using wrong attribute names**: Always use camelCase attributes.\n  - Wrong: `optional=\"true\"`, `generated=\"true\"`, `list=\"true\"`, `user-input=\"true\"`\n  - Right: `isOptional=\"true\"`, `isGenerated=\"true\"`, `isList=\"true\"`, `isUserInput=\"true\"`\n\n## Workflow\n\n1. **Understand the action** - What is the user/system trying to do?\n2. **Design the fields** - What information flows through this slice?\n3. **Propose before creating** - Get approval on the design first\n4. **Create the slice** - Run the command\n5. **Verify** - `eventmodeler show slice \"<name>\"`\n6. **Connect** - Create flows to/from other slices as needed\n\n## Best Practices\n\n1. **Get approval first** - Propose the design before creating\n2. **Use meaningful names** - Slice name should describe the action (\"Place Order\" not \"Order Slice\")\n3. **Include generated fields** - Events should have IDs and timestamps\n4. **Match field names** - Same names enable automatic mapping\n5. **Consider what's user input vs system data** - Mark appropriately\n6. **Name automation read models for their purpose** - \"OrderReadyForFulfillment\" not \"OrderData\"\n7. **Name processors descriptively** - \"Order Fulfillment Processor\" not just \"Processor\"\n";

package/dist/slices/guide/guides/create-slices.js

@@ -0,0 +1,303 @@
+export const meta = {
+    name: 'create-slices',
+    description: 'Create state-change, automation, and state-view slices with fields and flows',
+};
+export const content = `
+# Creating Slices
+
+There are three slice types in an event model. Each represents a different pattern of data flow.
+
+---
+
+## State-Change Slices
+
+A state-change slice represents a **user-initiated action** that changes system state:
+
+\`\`\`
+Screen → Command → Event
+\`\`\`
+
+- **Screen**: The UI where the user initiates the action
+- **Command**: The intent/request to change state
+- **Event**: The fact that state changed
+
+### When to Use
+
+Use state-change slices when:
+- A user performs an action (clicks a button, submits a form)
+- That action changes the state of an entity
+- Examples: "Place Order", "Cancel Subscription", "Update Profile", "Add Item to Cart"
+
+### Command Syntax
+
+\`\`\`bash
+eventmodeler create state-change-slice --xml '<state-change-slice name="Slice Name" [after="Other Slice"]>
+  <screen name="Screen Name">
+    <field name="fieldName" type="Type"/>
+  </screen>
+  <command name="CommandName">
+    <field name="fieldName" type="Type"/>
+  </command>
+  <event name="EventName">
+    <field name="fieldName" type="Type"/>
+  </event>
+</state-change-slice>'
+\`\`\`
+
+### Example: Place Order Slice
+
+\`\`\`bash
+eventmodeler create state-change-slice --xml '<state-change-slice name="Place Order">
+  <screen name="Checkout Screen">
+    <field name="customerId" type="UUID"/>
+    <field name="items" type="String" isUserInput="true"/>
+    <field name="shippingAddress" type="String" isUserInput="true"/>
+  </screen>
+  <command name="PlaceOrder">
+    <field name="customerId" type="UUID"/>
+    <field name="items" type="String"/>
+    <field name="shippingAddress" type="String"/>
+  </command>
+  <event name="OrderPlaced">
+    <field name="orderId" type="UUID" isGenerated="true"/>
+    <field name="customerId" type="UUID"/>
+    <field name="items" type="String"/>
+    <field name="shippingAddress" type="String"/>
+    <field name="placedAt" type="DateTime" isGenerated="true"/>
+  </event>
+</state-change-slice>'
+\`\`\`
+
+### Automatic Behavior
+
+1. **Positioning**: Places slice at end, or use \`after="Slice Name"\` or \`before="Slice Name"\`
+2. **Field mappings**: Automatically inferred by matching field names between Screen → Command and Command → Event
+3. **Flows**: Automatically creates Screen→Command and Command→Event flows
+
+---
+
+## Automation Slices
+
+An automation slice represents a **system-initiated action**:
+
+\`\`\`
+ReadModel → Processor → Command → Event
+\`\`\`
+
+- **ReadModel**: The state/data the processor needs to make decisions
+- **Processor**: The system component that decides when and how to act
+- **Command**: The intent/request to change state
+- **Event**: The fact that state changed
+
+### When to Use
+
+Use automation slices when:
+- The system automatically responds to events
+- No direct user interaction triggers the action
+- Examples: "Auto-assign Reviewer", "Send Reminder Email", "Calculate Shipping", "Process Payment"
+
+### Command Syntax
+
+\`\`\`bash
+eventmodeler create automation-slice --xml '<automation-slice name="Slice Name" [after="Other Slice"]>
+  <read-model name="ReadModelName">
+    <field name="fieldName" type="Type"/>
+  </read-model>
+  <processor name="Processor Name"/>
+  <command name="CommandName">
+    <field name="fieldName" type="Type"/>
+  </command>
+  <event name="EventName">
+    <field name="fieldName" type="Type"/>
+  </event>
+</automation-slice>'
+\`\`\`
+
+### Example: Auto-Fulfill Order
+
+\`\`\`bash
+eventmodeler create automation-slice --xml '<automation-slice name="Auto Fulfill Order" after="Place Order">
+  <read-model name="OrderReadyForFulfillment">
+    <field name="orderId" type="UUID"/>
+    <field name="isPaid" type="Boolean"/>
+    <field name="shippingAddress" type="String"/>
+  </read-model>
+  <processor name="Order Fulfillment Processor"/>
+  <command name="FulfillOrder">
+    <field name="orderId" type="UUID"/>
+    <field name="warehouseId" type="UUID" isGenerated="true"/>
+  </command>
+  <event name="OrderFulfilled">
+    <field name="orderId" type="UUID"/>
+    <field name="warehouseId" type="UUID"/>
+    <field name="fulfilledAt" type="DateTime" isGenerated="true"/>
+  </event>
+</automation-slice>'
+\`\`\`
+
+### Automatic Behavior
+
+1. **Positioning**: Places slice at end, or use \`after="Slice Name"\` or \`before="Slice Name"\`
+2. **Field mappings**: Automatically inferred by matching field names: ReadModel → Command, Command → Event
+3. **Flows**: Automatically creates ReadModel → Processor, Processor → Command, Command → Event
+
+### Connecting Trigger Events
+
+After creating the automation slice, connect external events to its read model:
+
+\`\`\`bash
+eventmodeler create flow --from "OrderPlaced" --to "OrderReadyForFulfillment"
+eventmodeler create flow --from "PaymentReceived" --to "OrderReadyForFulfillment"
+\`\`\`
+
+### Automation vs State-View Read Models
+
+| Automation ReadModel | State-View ReadModel |
+|---------------------|---------------------|
+| Inside automation slice | Standalone slice |
+| Feeds a Processor | Feeds a Screen |
+| "What the processor needs" | "What the user sees" |
+| Created with automation-slice | Created with state-view-slice |
+
+---
+
+## State-View Slices
+
+A state-view slice represents a **read model** - a projection of event data for querying:
+
+\`\`\`
+Read Model (fed by events)
+\`\`\`
+
+### When to Use
+
+Use state-view slices when:
+- You need to display data to users
+- A processor needs to query current state
+- You want to aggregate data from multiple events
+- Examples: "Order Summary", "User Dashboard", "Inventory Levels", "Account Balance"
+
+### Command Syntax
+
+\`\`\`bash
+eventmodeler create state-view-slice --xml '<state-view-slice name="Slice Name" [after="Other Slice"]>
+  <read-model name="ReadModelName">
+    <field name="fieldName" type="Type"/>
+  </read-model>
+</state-view-slice>'
+\`\`\`
+
+### Example: Order Summary View
+
+\`\`\`bash
+eventmodeler create state-view-slice --xml '<state-view-slice name="View Order Summary" after="Place Order">
+  <read-model name="OrderSummary">
+    <field name="orderId" type="UUID"/>
+    <field name="customerId" type="UUID"/>
+    <field name="customerName" type="String"/>
+    <field name="status" type="String"/>
+    <field name="totalAmount" type="Decimal"/>
+    <field name="itemCount" type="Int"/>
+    <field name="placedAt" type="DateTime"/>
+    <field name="lastUpdatedAt" type="DateTime"/>
+  </read-model>
+</state-view-slice>'
+\`\`\`
+
+### Connecting Events After Creation
+
+The \`create state-view-slice\` command only creates the read model. To complete the picture:
+
+1. Create flows from events: \`eventmodeler create flow --from "EventName" --to "ReadModelName"\`
+2. Map fields: \`eventmodeler map fields --flow "EventName→ReadModelName" --xml '...'\`
+3. Verify: \`eventmodeler show completeness "ReadModelName"\`
+
+---
+
+## Field Types
+
+\`UUID\`, \`String\`, \`Int\`, \`Long\`, \`Double\`, \`Decimal\`, \`Boolean\`, \`Date\`, \`DateTime\`, \`Custom\`
+
+## Field Attributes
+
+- \`isOptional="true"\` - Field may not have a value
+- \`isGenerated="true"\` - System-generated (e.g., IDs, timestamps), not from user input
+- \`isUserInput="true"\` - Entered by the user on the screen
+- \`isList="true"\` - Field is a list/array of the specified type
+
+## Working with Lists and Custom Types
+
+**List of primitives** - use \`isList="true"\` with any valid type:
+\`\`\`xml
+<field name="tags" type="String" isList="true"/>
+<field name="quantities" type="Int" isList="true"/>
+\`\`\`
+
+### Custom Types (Nested Objects)
+
+**CRITICAL: Custom fields MUST contain subfields.** The \`type="Custom"\` indicates a nested object structure, and the nested \`<field>\` elements define its properties. A Custom field without subfields is invalid and creates an empty, useless type.
+
+**Custom type with nested fields:**
+\`\`\`xml
+<field name="address" type="Custom">
+  <field name="street" type="String"/>
+  <field name="city" type="String"/>
+  <field name="postalCode" type="String"/>
+</field>
+\`\`\`
+
+**List of custom objects** - combine \`type="Custom"\` with \`isList="true"\`:
+\`\`\`xml
+<field name="lineItems" type="Custom" isList="true">
+  <field name="productId" type="UUID"/>
+  <field name="quantity" type="Int"/>
+  <field name="unitPrice" type="Decimal"/>
+</field>
+\`\`\`
+
+**Nested custom types** - subfields can themselves be Custom types:
+\`\`\`xml
+<field name="customer" type="Custom">
+  <field name="customerId" type="UUID"/>
+  <field name="name" type="String"/>
+  <field name="billingAddress" type="Custom">
+    <field name="street" type="String"/>
+    <field name="city" type="String"/>
+    <field name="country" type="String"/>
+  </field>
+</field>
+\`\`\`
+
+## Common Mistakes
+
+- **Creating empty Custom fields**: Custom fields MUST have subfields that define their structure.
+  - Wrong: \`<field name="address" type="Custom"/>\`
+  - Right: \`<field name="address" type="Custom"><field name="street" type="String"/>...</field>\`
+
+- **Using "List" as a field type**: "List" is not a valid type. Use \`isList="true"\` with a valid type instead.
+  - Wrong: \`<field name="items" type="List"/>\`
+  - Right: \`<field name="items" type="String" isList="true"/>\`
+
+- **Using wrong attribute names**: Always use camelCase attributes.
+  - Wrong: \`optional="true"\`, \`generated="true"\`, \`list="true"\`, \`user-input="true"\`
+  - Right: \`isOptional="true"\`, \`isGenerated="true"\`, \`isList="true"\`, \`isUserInput="true"\`
+
+## Workflow
+
+1. **Understand the action** - What is the user/system trying to do?
+2. **Design the fields** - What information flows through this slice?
+3. **Propose before creating** - Get approval on the design first
+4. **Create the slice** - Run the command
+5. **Verify** - \`eventmodeler show slice "<name>"\`
+6. **Connect** - Create flows to/from other slices as needed
+
+## Best Practices
+
+1. **Get approval first** - Propose the design before creating
+2. **Use meaningful names** - Slice name should describe the action ("Place Order" not "Order Slice")
+3. **Include generated fields** - Events should have IDs and timestamps
+4. **Match field names** - Same names enable automatic mapping
+5. **Consider what's user input vs system data** - Mark appropriately
+6. **Name automation read models for their purpose** - "OrderReadyForFulfillment" not "OrderData"
+7. **Name processors descriptively** - "Order Fulfillment Processor" not just "Processor"
+`;

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

@@ -0,0 +1,5 @@
+export declare const meta: {
+    name: string;
+    description: string;
+};
+export declare const content = "\n# Exploring Event Models with the CLI\n\nThe `eventmodeler` CLI lets you query and explore event models linked to your project.\n\n## Getting an Overview\n\n**Start here** to understand the model:\n\n```bash\neventmodeler summary\n```\nShows statistics: total slices, events, commands, read models, etc.\n\n```bash\neventmodeler list slices\n```\nLists all slices with their status (created, in-progress, blocked, done). Slices represent vertical features.\n\n```bash\neventmodeler list slices --chapter \"<name>\"\n```\nLists only slices within a specific chapter.\n\n```bash\neventmodeler list chapters\n```\nLists chapters - timeline sections that group slices.\n\n## Listing Elements\n\n```bash\neventmodeler list events      # All events in the model\neventmodeler list commands    # All commands in the model\neventmodeler list readmodels  # All read models\neventmodeler list screens     # All screens\neventmodeler list processors  # All processors\neventmodeler list scenarios   # All scenarios\neventmodeler list aggregates  # All aggregates (event groupings)\neventmodeler list actors      # All actors (user/system roles)\n```\n\nAll `list` commands support `--format xml|json`.\n\n## Searching\n\n```bash\neventmodeler search \"<term>\"\n```\nSearches across all entity names: slices, events, commands, read models, aggregates, and actors.\n\n## Drilling Into Details\n\n### Show a Slice\n```bash\neventmodeler show slice \"<name>\"\n```\nReturns XML with:\n- All components in the slice (screens, commands, events, read-models, processors)\n- **Inline flow annotations** on each component showing `<flows-from>` and `<flows-to>` connections\n- Fields on each component with types and attributes\n- Information flow (which components connect to which)\n- **Inbound flows**: External elements flowing INTO this slice (with field mappings)\n- **Outbound flows**: Elements in this slice flowing OUT to other slices (with field mappings)\n- Scenarios (Given-When-Then test cases)\n\nThe inbound/outbound flows show cross-slice dependencies - crucial for understanding how a slice integrates with the rest of the system.\n\n**Scenarios are key** - they define the slice's behavior and give it context. A slice's scenarios show:\n- **Given**: What events have already occurred (the starting state)\n- **When**: What command is being executed with what field values\n- **Then**: The expected outcome - either:\n  - Events that should be produced\n  - An error that should occur\n  - A read model assertion (expected state)\n\nExample scenario in slice output:\n```xml\n<scenarios>\n  <scenario name=\"Successfully place order\">\n    <given>\n      <event type=\"CustomerRegistered\">customerId: \"123\"</event>\n    </given>\n    <when>\n      <command type=\"PlaceOrder\">customerId: \"123\", items: [...]</command>\n    </when>\n    <then>\n      <event type=\"OrderPlaced\">orderId: \"456\", customerId: \"123\"</event>\n    </then>\n  </scenario>\n  <scenario name=\"Cannot place order without items\">\n    <when>\n      <command type=\"PlaceOrder\">customerId: \"123\", items: []</command>\n    </when>\n    <then>\n      <error type=\"ValidationError\">Order must contain at least one item</error>\n    </then>\n  </scenario>\n</scenarios>\n```\n\nReading scenarios helps understand:\n- What preconditions the slice expects\n- What inputs the command accepts\n- What the happy path looks like\n- What error cases are handled\n\n### Show an Event or Command\n```bash\neventmodeler show event \"<name>\"\neventmodeler show command \"<name>\"\n```\nReturns XML with the element's fields and connections.\n\n### Show Read Models, Screens, and Processors\n```bash\neventmodeler show readmodel \"<name>\"\neventmodeler show screen \"<name>\"\neventmodeler show processor \"<name>\"\n```\nUse these for detailed flow context:\n- `show readmodel`: fields, source events, and who consumes it\n- `show screen`: fields, source read models, and triggered commands\n- `show processor`: fields, source read models, and triggered commands\n\n### Show Aggregate and Scenario\n```bash\neventmodeler show aggregate \"<name>\"\neventmodeler show scenario \"<name>\"\n```\n- `show aggregate`: aggregate ID configuration and contained events\n- `show scenario`: complete Given-When-Then with field values\n\n### Show a Chapter\n```bash\neventmodeler show chapter \"<name>\"\n```\nShows the chapter with:\n- All slices within the chapter\n- **Flow graph**: How slices connect to each other (which events flow to which read models, etc.) with field mappings\n- **External dependencies**:\n  - Inbound: Flows from outside the chapter into slices within it\n  - Outbound: Flows from slices in this chapter to elements outside it\n\nUse `show chapter` to understand the relationships between slices in a feature area. Use `list slices --chapter` for a simple list without flow details.\n\n### Show an Actor\n```bash\neventmodeler show actor \"<name>\"\n```\nShows the actor and lists all screens associated with it.\n\n## Managing Slice Status\n\nSlices have a status that tracks their progress: `created`, `in-progress`, `blocked`, `done`.\n\n```bash\n# Mark a slice as in progress\neventmodeler mark \"Place Order\" in-progress\n\n# Mark a slice as done\neventmodeler mark \"Place Order\" done\n\n# Mark a slice as blocked\neventmodeler mark \"Place Order\" blocked\n\n# Reset to created\neventmodeler mark \"Place Order\" created\n```\n\nUse `list slices` to see current statuses.\n\n## Checking Information Completeness\n\nInformation completeness tracks whether fields flow correctly between connected elements.\n\n### Check a Specific Element\n```bash\neventmodeler show completeness \"<name>\"\n```\nAuto-detects the element type (command, event, read model, screen, or processor) and shows:\n- Incoming flows to that element\n- Which fields are satisfied (have a source)\n- Which fields are unsatisfied (missing a source)\n\n### Check the Entire Model\n```bash\neventmodeler show model-completeness\n```\nProject-wide view of all information flows:\n- Summary: complete count, incomplete count, total\n- Lists all incomplete flows with their unsatisfied fields\n\n### Check Aggregate ID Fields\n```bash\neventmodeler show aggregate-completeness \"<aggregate-name>\"\n```\nChecks if all events in an aggregate have the aggregate's ID field.\n\n## Using Element IDs Instead of Names\n\nEvery command that accepts an element name also accepts an element ID with the `id:` prefix. This works everywhere: `show`, `add field`, `remove field`, `update field`, `add scenario`, `remove scenario`, `create flow`, `remove flow`, `map fields`, `mark`, `codegen`, and `search`.\n\n```bash\n# Use a full UUID\neventmodeler show event \"id:abc12345-1234-5678-9abc-def012345678\"\n\n# Or just a unique prefix (first 8 chars is usually enough)\neventmodeler show event \"id:abc12345\"\n\n# Works with any command\neventmodeler add field \"id:abc12345\" --xml '<field name=\"status\" type=\"String\"/>'\neventmodeler update field \"id:abc12345\" --field \"status\" --optional true\neventmodeler create flow --from \"id:abc12345\" --to \"OrderSummary\"\n```\n\nThis is essential when multiple elements share the same name (e.g., linked copies). The CLI will tell you when names are ambiguous and show the IDs to use. Find element IDs via `list` commands:\n\n```bash\neventmodeler list events    # shows id=\"...\" for each event\neventmodeler list commands  # shows id=\"...\" for each command\n```\n\n## Exploration Strategy\n\nWhen exploring an unfamiliar event model:\n\n1. **Get the big picture**: `eventmodeler summary` \u2192 understand scale\n2. **See the features**: `eventmodeler list slices` \u2192 what does this system do?\n3. **Understand organization**: `eventmodeler list chapters` \u2192 how is it structured over time?\n4. **Dive into a slice**: `eventmodeler show slice \"<name>\"` \u2192 how does one feature work?\n5. **Read the scenarios**: They tell you what the slice actually does, its preconditions, and edge cases\n6. **Search for specifics**: `eventmodeler search \"<term>\"` \u2192 find related elements\n\nWhen checking model health:\n1. **Overall completeness**: `eventmodeler show model-completeness` \u2192 any broken flows?\n2. **Specific element**: `eventmodeler show completeness \"<name>\"` \u2192 what's missing here?\n3. **Aggregate consistency**: `eventmodeler show aggregate-completeness \"<name>\"` \u2192 ID fields present?\n\nWhen looking for something specific:\n- Know the feature name? \u2192 `show slice`\n- Know an event name? \u2192 `show event` or `search`\n- Know a read model/screen/processor name? \u2192 `show readmodel` / `show screen` / `show processor`\n- Need scenario details? \u2192 `list scenarios` then `show scenario`\n- Want all events? \u2192 `list events`\n- Checking data flow? \u2192 `show completeness` or `show model-completeness`\n";