eventmodeler 0.4.6 → 0.5.0

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

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

package/dist/slices/guide/guides/information-flow.d.ts

@@ -0,0 +1,5 @@
+export declare const meta: {
+    name: string;
+    description: string;
+};
+export declare const content = "\n# Information Flow: Fields, Mappings, and Completeness\n\nThis guide covers the full lifecycle of information in an event model: designing fields, adding them to elements, mapping data between connected elements, updating field properties, and verifying completeness.\n\n---\n\n## Designing Read Models\n\nRead models are projections of event data - views that serve specific screens or use cases. Every field in a read model should trace back to event fields.\n\n### Understand the Context\n```bash\n# Look at the slice containing the read model\neventmodeler show slice \"<slice-name>\"\n\n# Check current completeness - what's missing?\neventmodeler show completeness \"<read-model-name>\"\n\n# See what events feed into this read model\neventmodeler list events\n```\n\n### Design the Fields\nBased on the use case, identify what fields are needed:\n- **Identity fields** - IDs to identify the entity\n- **Display fields** - What the user sees\n- **Status fields** - Current state\n- **Computed fields** - Aggregations, counts, derived values\n- **Timestamp fields** - When things happened\n\n### Propose Before Adding\n```\nI suggest these fields for the OrderHistory read model:\n- orderId (UUID) - identifies the order\n- customerId (UUID) - who placed it\n- status (String) - current status: pending, shipped, delivered, cancelled\n- total (Decimal) - order total\n- placedAt (DateTime) - when it was placed\n- lastUpdatedAt (DateTime) - when status last changed\n\nDoes this look right?\n```\n\n## Adding Fields\n\nField types: `UUID`, `String`, `Int`, `Long`, `Double`, `Decimal`, `Boolean`, `Date`, `DateTime`, `Custom`\n\n```bash\n# Add a simple field\neventmodeler add field --read-model \"OrderSummary\" --xml '<field name=\"orderId\" type=\"UUID\"/>'\n\n# Add an optional field\neventmodeler add field --read-model \"OrderSummary\" --xml '<field name=\"cancelledAt\" type=\"DateTime\" isOptional=\"true\"/>'\n\n# Add a list field\neventmodeler add field --read-model \"OrderSummary\" --xml '<field name=\"itemIds\" type=\"UUID\" isList=\"true\"/>'\n\n# Add a complex/nested field\neventmodeler add field --read-model \"OrderSummary\" --xml '<field name=\"shippingAddress\" 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**CRITICAL: Custom fields MUST contain subfields.** A Custom field without subfields is invalid.\n\n### Lists and Custom Types\n\n**List of custom objects** - combine `type=\"Custom\"` with `isList=\"true\"`:\n```bash\neventmodeler add field --read-model \"OrderSummary\" --xml '<field name=\"lineItems\" type=\"Custom\" isList=\"true\">\n  <field name=\"productId\" type=\"UUID\"/>\n  <field name=\"productName\" type=\"String\"/>\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:\n```bash\neventmodeler add field --read-model \"OrderSummary\" --xml '<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---\n\n## Mapping Fields on Flows\n\nField mappings define how data flows from source elements to target elements. When you connect an Event to a ReadModel with a flow, the field mappings specify which event fields populate which read model fields.\n\n### Command Syntax\n\n```bash\neventmodeler map fields --flow \"<Source>\u2192<Target>\" --xml '<mapping from=\"sourceField\" to=\"targetField\"/>'\n```\n\nOr with multiple mappings:\n\n```bash\neventmodeler map fields --flow \"<Source>\u2192<Target>\" --xml '\n  <mapping from=\"orderId\" to=\"orderId\"/>\n  <mapping from=\"customerId\" to=\"customerId\"/>\n  <mapping from=\"totalAmount\" to=\"total\"/>\n'\n```\n\n### Flow Identifier Formats\n\nThe `--flow` argument accepts:\n\n1. **Name arrow format** (most common): `\"SourceName\u2192TargetName\"` or `\"SourceName->TargetName\"`\n2. **Element ID prefix** (for duplicates): `\"id:abc12345\u2192TargetName\"`\n3. **Flow ID directly**: The UUID of the flow itself\n\nNote: The `id:` prefix works with every command, not just `map fields`. See `eventmodeler guide explore` for details.\n\n### JSON Alternative\n\n```bash\neventmodeler map fields --flow \"OrderPlaced\u2192OrderSummary\" --json '[\n  {\"from\": \"orderId\", \"to\": \"orderId\"},\n  {\"from\": \"customerId\", \"to\": \"customerId\"}\n]'\n```\n\n### Workflow\n\n1. **Find flows needing mappings**: `eventmodeler show model-completeness`\n2. **See source fields**: `eventmodeler show event \"OrderPlaced\"`\n3. **See target fields**: `eventmodeler show completeness \"OrderSummary\"`\n4. **Create mappings**: `eventmodeler map fields --flow \"OrderPlaced\u2192OrderSummary\" --xml '...'`\n5. **Verify**: `eventmodeler show completeness \"OrderSummary\"`\n\n### Mapping Nested Fields\n\nFor Custom (nested) field types, use dot notation:\n\n```bash\neventmodeler map fields --flow \"OrderPlaced\u2192OrderSummary\" --xml '\n  <mapping from=\"shippingAddress.street\" to=\"deliveryAddress.street\"/>\n  <mapping from=\"shippingAddress.city\" to=\"deliveryAddress.city\"/>\n  <mapping from=\"shippingAddress.postalCode\" to=\"deliveryAddress.zip\"/>\n'\n```\n\n### Multiple Flows to Same Target\n\nA read model often receives data from multiple events. Map each flow separately:\n\n```bash\n# Initial data from OrderPlaced\neventmodeler map fields --flow \"OrderPlaced\u2192OrderSummary\" --xml '\n  <mapping from=\"orderId\" to=\"orderId\"/>\n  <mapping from=\"customerId\" to=\"customerId\"/>\n  <mapping from=\"totalAmount\" to=\"total\"/>\n'\n\n# Status updates from OrderShipped\neventmodeler map fields --flow \"OrderShipped\u2192OrderSummary\" --xml '\n  <mapping from=\"shippedAt\" to=\"shippedDate\"/>\n  <mapping from=\"trackingNumber\" to=\"trackingNumber\"/>\n'\n```\n\n### Updating Existing Mappings\n\nRunning `map fields` again **merges** with existing mappings:\n- New mappings are added\n- If a target field already has a mapping, it's replaced with the new source\n\n### Common Mapping Patterns\n\n| Pattern | Example |\n|---------|---------|\n| Identity | `<mapping from=\"orderId\" to=\"orderId\"/>` |\n| Rename | `<mapping from=\"totalAmount\" to=\"total\"/>` |\n| Nested to flat | `<mapping from=\"customer.id\" to=\"customerId\"/>` |\n| Flat to nested | `<mapping from=\"street\" to=\"address.street\"/>` |\n\n---\n\n## Updating Field Properties\n\nUse `update field` to modify field attributes without changing the field's name or structure.\n\n### Command Syntax\n\n```bash\neventmodeler update field --<element-type> \"<name>\" --field \"<field-name>\" [options]\n```\n\nElement types: `--command`, `--event`, `--read-model`, `--screen`, `--processor`\n\n### Available Options\n\n| Option | Values | Description |\n|--------|--------|-------------|\n| `--optional` | `true`/`false` | Mark field as not required for completeness |\n| `--generated` | `true`/`false` | Mark field as system-generated (not from user input) |\n| `--user-input` | `true`/`false` | Mark field as user-provided (screens only) |\n| `--type` | Field type | Change the field's data type |\n\n### Examples\n\n```bash\n# Mark a field as optional\neventmodeler update field --event \"OrderPlaced\" --field \"promoCode\" --optional true\n\n# Mark a field as system-generated\neventmodeler update field --event \"OrderPlaced\" --field \"orderId\" --generated true\n\n# Mark screen fields as user input\neventmodeler update field --screen \"Checkout\" --field \"email\" --user-input true\n\n# Change a field's type\neventmodeler update field --read-model \"OrderSummary\" --field \"total\" --type Decimal\n\n# Combine multiple updates\neventmodeler update field --event \"UserRegistered\" --field \"createdAt\" --generated true --optional false\n```\n\n### Updating Nested Fields\n\nUse dot notation for fields inside Custom types:\n\n```bash\neventmodeler update field --event \"OrderPlaced\" --field \"shippingAddress.postalCode\" --optional true\n```\n\n### Field Property Meanings\n\n**isOptional**: Field may not always have a value. Completeness checks don't require this field to have a mapping source.\n\n**isGenerated**: Field is system-generated, not derived from other fields. Completeness checks don't require this field to have a mapping source. Use for: IDs, timestamps, sequence numbers, computed values.\n\n**isUserInput** (screens only): Field comes from user input on the screen. Identifies which screen fields are inputs vs. display-only.\n\n---\n\n## Removing Fields\n\n```bash\n# Remove a field from an event\neventmodeler remove field --event \"OrderPlaced\" --field \"legacyId\"\n\n# Remove a field from a read model\neventmodeler remove field --read-model \"OrderSummary\" --field \"deprecatedStatus\"\n\n# Remove a nested field using dot notation\neventmodeler remove field --event \"OrderPlaced\" --field \"metadata.debugInfo\"\n```\n\n**Caution**: Removing a field may break existing field mappings. Check completeness first:\n```bash\neventmodeler show completeness \"<element-name>\"\n```\n\n---\n\n## Checking Completeness\n\n### Check a Specific Element\n```bash\neventmodeler show completeness \"<name>\"\n```\nShows incoming flows and which fields are satisfied vs unsatisfied.\n\n### Check the Entire Model\n```bash\neventmodeler show model-completeness\n```\nProject-wide view: complete count, incomplete count, and all incomplete flows with their unsatisfied fields.\n\n### Check Aggregate ID Fields\n```bash\neventmodeler show aggregate-completeness \"<aggregate-name>\"\n```\n\n---\n\n## Common Mistakes\n\n- **Creating empty Custom fields**: Custom fields MUST have subfields.\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**: 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\"`\n  - Right: `isOptional=\"true\"`, `isGenerated=\"true\"`, `isList=\"true\"`\n\n## Best Practices\n\n1. **Get approval before adding fields** - Propose the design, let the user confirm\n2. **Consider all source events** - A read model may need data from multiple events\n3. **Use appropriate types** - `Decimal` for money, `DateTime` for timestamps\n4. **Mark optional fields** - Fields that may not always have values (e.g., `cancelledAt`)\n5. **Mark generated fields early** - When creating slices, immediately mark IDs and timestamps as generated\n6. **Map all fields at once** - More efficient than one mapping at a time\n7. **Verify after mapping** - Run `show completeness` to confirm all fields are satisfied\n8. **Check mappings before removing** - Removing a field can break existing mappings\n";

package/dist/slices/guide/guides/information-flow.js

@@ -0,0 +1,318 @@
+export const meta = {
+    name: 'information-flow',
+    description: 'Design fields, map data between elements, update properties, and check completeness',
+};
+export const content = `
+# Information Flow: Fields, Mappings, and Completeness
+
+This guide covers the full lifecycle of information in an event model: designing fields, adding them to elements, mapping data between connected elements, updating field properties, and verifying completeness.
+
+---
+
+## Designing Read Models
+
+Read models are projections of event data - views that serve specific screens or use cases. Every field in a read model should trace back to event fields.
+
+### Understand the Context
+\`\`\`bash
+# Look at the slice containing the read model
+eventmodeler show slice "<slice-name>"
+
+# Check current completeness - what's missing?
+eventmodeler show completeness "<read-model-name>"
+
+# See what events feed into this read model
+eventmodeler list events
+\`\`\`
+
+### Design the Fields
+Based on the use case, identify what fields are needed:
+- **Identity fields** - IDs to identify the entity
+- **Display fields** - What the user sees
+- **Status fields** - Current state
+- **Computed fields** - Aggregations, counts, derived values
+- **Timestamp fields** - When things happened
+
+### Propose Before Adding
+\`\`\`
+I suggest these fields for the OrderHistory read model:
+- orderId (UUID) - identifies the order
+- customerId (UUID) - who placed it
+- status (String) - current status: pending, shipped, delivered, cancelled
+- total (Decimal) - order total
+- placedAt (DateTime) - when it was placed
+- lastUpdatedAt (DateTime) - when status last changed
+
+Does this look right?
+\`\`\`
+
+## Adding Fields
+
+Field types: \`UUID\`, \`String\`, \`Int\`, \`Long\`, \`Double\`, \`Decimal\`, \`Boolean\`, \`Date\`, \`DateTime\`, \`Custom\`
+
+\`\`\`bash
+# Add a simple field
+eventmodeler add field --read-model "OrderSummary" --xml '<field name="orderId" type="UUID"/>'
+
+# Add an optional field
+eventmodeler add field --read-model "OrderSummary" --xml '<field name="cancelledAt" type="DateTime" isOptional="true"/>'
+
+# Add a list field
+eventmodeler add field --read-model "OrderSummary" --xml '<field name="itemIds" type="UUID" isList="true"/>'
+
+# Add a complex/nested field
+eventmodeler add field --read-model "OrderSummary" --xml '<field name="shippingAddress" type="Custom">
+  <field name="street" type="String"/>
+  <field name="city" type="String"/>
+  <field name="postalCode" type="String"/>
+</field>'
+\`\`\`
+
+**CRITICAL: Custom fields MUST contain subfields.** A Custom field without subfields is invalid.
+
+### Lists and Custom Types
+
+**List of custom objects** - combine \`type="Custom"\` with \`isList="true"\`:
+\`\`\`bash
+eventmodeler add field --read-model "OrderSummary" --xml '<field name="lineItems" type="Custom" isList="true">
+  <field name="productId" type="UUID"/>
+  <field name="productName" type="String"/>
+  <field name="quantity" type="Int"/>
+  <field name="unitPrice" type="Decimal"/>
+</field>'
+\`\`\`
+
+**Nested custom types** - subfields can themselves be Custom:
+\`\`\`bash
+eventmodeler add field --read-model "OrderSummary" --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>'
+\`\`\`
+
+---
+
+## Mapping Fields on Flows
+
+Field mappings define how data flows from source elements to target elements. When you connect an Event to a ReadModel with a flow, the field mappings specify which event fields populate which read model fields.
+
+### Command Syntax
+
+\`\`\`bash
+eventmodeler map fields --flow "<Source>→<Target>" --xml '<mapping from="sourceField" to="targetField"/>'
+\`\`\`
+
+Or with multiple mappings:
+
+\`\`\`bash
+eventmodeler map fields --flow "<Source>→<Target>" --xml '
+  <mapping from="orderId" to="orderId"/>
+  <mapping from="customerId" to="customerId"/>
+  <mapping from="totalAmount" to="total"/>
+'
+\`\`\`
+
+### Flow Identifier Formats
+
+The \`--flow\` argument accepts:
+
+1. **Name arrow format** (most common): \`"SourceName→TargetName"\` or \`"SourceName->TargetName"\`
+2. **Element ID prefix** (for duplicates): \`"id:abc12345→TargetName"\`
+3. **Flow ID directly**: The UUID of the flow itself
+
+Note: The \`id:\` prefix works with every command, not just \`map fields\`. See \`eventmodeler guide explore\` for details.
+
+### JSON Alternative
+
+\`\`\`bash
+eventmodeler map fields --flow "OrderPlaced→OrderSummary" --json '[
+  {"from": "orderId", "to": "orderId"},
+  {"from": "customerId", "to": "customerId"}
+]'
+\`\`\`
+
+### Workflow
+
+1. **Find flows needing mappings**: \`eventmodeler show model-completeness\`
+2. **See source fields**: \`eventmodeler show event "OrderPlaced"\`
+3. **See target fields**: \`eventmodeler show completeness "OrderSummary"\`
+4. **Create mappings**: \`eventmodeler map fields --flow "OrderPlaced→OrderSummary" --xml '...'\`
+5. **Verify**: \`eventmodeler show completeness "OrderSummary"\`
+
+### Mapping Nested Fields
+
+For Custom (nested) field types, use dot notation:
+
+\`\`\`bash
+eventmodeler map fields --flow "OrderPlaced→OrderSummary" --xml '
+  <mapping from="shippingAddress.street" to="deliveryAddress.street"/>
+  <mapping from="shippingAddress.city" to="deliveryAddress.city"/>
+  <mapping from="shippingAddress.postalCode" to="deliveryAddress.zip"/>
+'
+\`\`\`
+
+### Multiple Flows to Same Target
+
+A read model often receives data from multiple events. Map each flow separately:
+
+\`\`\`bash
+# Initial data from OrderPlaced
+eventmodeler map fields --flow "OrderPlaced→OrderSummary" --xml '
+  <mapping from="orderId" to="orderId"/>
+  <mapping from="customerId" to="customerId"/>
+  <mapping from="totalAmount" to="total"/>
+'
+
+# Status updates from OrderShipped
+eventmodeler map fields --flow "OrderShipped→OrderSummary" --xml '
+  <mapping from="shippedAt" to="shippedDate"/>
+  <mapping from="trackingNumber" to="trackingNumber"/>
+'
+\`\`\`
+
+### Updating Existing Mappings
+
+Running \`map fields\` again **merges** with existing mappings:
+- New mappings are added
+- If a target field already has a mapping, it's replaced with the new source
+
+### Common Mapping Patterns
+
+| Pattern | Example |
+|---------|---------|
+| Identity | \`<mapping from="orderId" to="orderId"/>\` |
+| Rename | \`<mapping from="totalAmount" to="total"/>\` |
+| Nested to flat | \`<mapping from="customer.id" to="customerId"/>\` |
+| Flat to nested | \`<mapping from="street" to="address.street"/>\` |
+
+---
+
+## Updating Field Properties
+
+Use \`update field\` to modify field attributes without changing the field's name or structure.
+
+### Command Syntax
+
+\`\`\`bash
+eventmodeler update field --<element-type> "<name>" --field "<field-name>" [options]
+\`\`\`
+
+Element types: \`--command\`, \`--event\`, \`--read-model\`, \`--screen\`, \`--processor\`
+
+### Available Options
+
+| Option | Values | Description |
+|--------|--------|-------------|
+| \`--optional\` | \`true\`/\`false\` | Mark field as not required for completeness |
+| \`--generated\` | \`true\`/\`false\` | Mark field as system-generated (not from user input) |
+| \`--user-input\` | \`true\`/\`false\` | Mark field as user-provided (screens only) |
+| \`--type\` | Field type | Change the field's data type |
+
+### Examples
+
+\`\`\`bash
+# Mark a field as optional
+eventmodeler update field --event "OrderPlaced" --field "promoCode" --optional true
+
+# Mark a field as system-generated
+eventmodeler update field --event "OrderPlaced" --field "orderId" --generated true
+
+# Mark screen fields as user input
+eventmodeler update field --screen "Checkout" --field "email" --user-input true
+
+# Change a field's type
+eventmodeler update field --read-model "OrderSummary" --field "total" --type Decimal
+
+# Combine multiple updates
+eventmodeler update field --event "UserRegistered" --field "createdAt" --generated true --optional false
+\`\`\`
+
+### Updating Nested Fields
+
+Use dot notation for fields inside Custom types:
+
+\`\`\`bash
+eventmodeler update field --event "OrderPlaced" --field "shippingAddress.postalCode" --optional true
+\`\`\`
+
+### Field Property Meanings
+
+**isOptional**: Field may not always have a value. Completeness checks don't require this field to have a mapping source.
+
+**isGenerated**: Field is system-generated, not derived from other fields. Completeness checks don't require this field to have a mapping source. Use for: IDs, timestamps, sequence numbers, computed values.
+
+**isUserInput** (screens only): Field comes from user input on the screen. Identifies which screen fields are inputs vs. display-only.
+
+---
+
+## Removing Fields
+
+\`\`\`bash
+# Remove a field from an event
+eventmodeler remove field --event "OrderPlaced" --field "legacyId"
+
+# Remove a field from a read model
+eventmodeler remove field --read-model "OrderSummary" --field "deprecatedStatus"
+
+# Remove a nested field using dot notation
+eventmodeler remove field --event "OrderPlaced" --field "metadata.debugInfo"
+\`\`\`
+
+**Caution**: Removing a field may break existing field mappings. Check completeness first:
+\`\`\`bash
+eventmodeler show completeness "<element-name>"
+\`\`\`
+
+---
+
+## Checking Completeness
+
+### Check a Specific Element
+\`\`\`bash
+eventmodeler show completeness "<name>"
+\`\`\`
+Shows incoming flows and which fields are satisfied vs unsatisfied.
+
+### Check the Entire Model
+\`\`\`bash
+eventmodeler show model-completeness
+\`\`\`
+Project-wide view: complete count, incomplete count, and all incomplete flows with their unsatisfied fields.
+
+### Check Aggregate ID Fields
+\`\`\`bash
+eventmodeler show aggregate-completeness "<aggregate-name>"
+\`\`\`
+
+---
+
+## Common Mistakes
+
+- **Creating empty Custom fields**: Custom fields MUST have subfields.
+  - Wrong: \`<field name="address" type="Custom"/>\`
+  - Right: \`<field name="address" type="Custom"><field name="street" type="String"/>...</field>\`
+
+- **Using "List" as a field 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"\`
+  - Right: \`isOptional="true"\`, \`isGenerated="true"\`, \`isList="true"\`
+
+## Best Practices
+
+1. **Get approval before adding fields** - Propose the design, let the user confirm
+2. **Consider all source events** - A read model may need data from multiple events
+3. **Use appropriate types** - \`Decimal\` for money, \`DateTime\` for timestamps
+4. **Mark optional fields** - Fields that may not always have values (e.g., \`cancelledAt\`)
+5. **Mark generated fields early** - When creating slices, immediately mark IDs and timestamps as generated
+6. **Map all fields at once** - More efficient than one mapping at a time
+7. **Verify after mapping** - Run \`show completeness\` to confirm all fields are satisfied
+8. **Check mappings before removing** - Removing a field can break existing mappings
+`;

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

@@ -0,0 +1,5 @@
+export declare const meta: {
+    name: string;
+    description: string;
+};
+export declare const content = "\n# Designing Scenarios for Slices\n\nScenarios define the behavior of a slice. There are two main scenario patterns:\n\n1. **State-Change Scenarios** (for state-change slices): Given events \u2192 When command \u2192 Then events/error\n2. **Automation Scenarios** (for automation slices): Given events \u2192 Then command (simpler Given-Then format)\n\n## Your Workflow\n\nWhen helping design scenarios for a slice:\n\n### 1. Gather Context\n```bash\n# Look at the slice to understand its components\neventmodeler show slice \"<slice-name>\"\n\n# See what chapter it belongs to and nearby slices for context\neventmodeler list chapters\neventmodeler show chapter \"<chapter-name>\"\n\n# List all events to understand what's available for Given clauses\neventmodeler list events\n```\n\n### 2. Identify the Slice Type\n\n**State-Change Slice** (Screen \u2192 Command \u2192 Event):\n- User triggers a command\n- Command produces event(s)\n- Use: Given \u2192 When command \u2192 Then events/error\n\n**Automation Slice** (ReadModel \u2192 Processor \u2192 Command \u2192 Event):\n- Events trigger the processor to issue a command\n- Use simpler Given \u2192 Then format (no When)\n- Given: All events that lead to the trigger condition\n- Then: The command that should be dispatched (or noCommand)\n\n### 3. Design Scenarios by Type\n\n---\n\n## State-Change Scenarios\n\nFor slices where a user action triggers a command:\n\n**Happy Path** - The command succeeds under normal conditions\n- Given: Any required preconditions (existing events)\n- When: The command with valid input\n- Then: The expected event(s) with field values\n\n**Validation Errors** - Bad input is rejected\n- Given: (may be empty)\n- When: Command with invalid input\n- Then: Error with message\n\n**Business Rule Violations** - Valid input but rule prevents action\n- Given: Events that create a state where the action isn't allowed\n- When: The command\n- Then: Error explaining why\n\n### State-Change Examples\n\n```bash\n# Happy path - command succeeds\neventmodeler add scenario --slice \"<slice-name>\" --xml '<scenario name=\"Successfully place order\" description=\"A registered customer can place an order with valid items\">\n  <given>\n    <event name=\"CustomerRegistered\">\n      <field name=\"customerId\">cust-123</field>\n    </event>\n  </given>\n  <when>\n    <command name=\"PlaceOrder\">\n      <field name=\"customerId\">cust-123</field>\n      <field name=\"items\">[{\"productId\": \"prod-1\", \"quantity\": 2}]</field>\n    </command>\n  </when>\n  <then type=\"events\">\n    <event name=\"OrderPlaced\">\n      <field name=\"orderId\">order-456</field>\n      <field name=\"customerId\">cust-123</field>\n    </event>\n  </then>\n</scenario>'\n```\n\n```bash\n# Validation error\neventmodeler add scenario --slice \"<slice-name>\" --xml '<scenario name=\"Cannot place empty order\" description=\"Orders must contain at least one item - empty item lists are rejected\">\n  <when>\n    <command name=\"PlaceOrder\">\n      <field name=\"customerId\">cust-123</field>\n      <field name=\"items\">[]</field>\n    </command>\n  </when>\n  <then type=\"error\" errorType=\"ValidationError\">Order must contain at least one item</then>\n</scenario>'\n```\n\n```bash\n# Business rule violation\neventmodeler add scenario --slice \"Cancel Order\" --xml '<scenario name=\"Cannot cancel shipped order\" description=\"Once an order has been shipped, it can no longer be cancelled\">\n  <given>\n    <event name=\"OrderPlaced\">\n      <field name=\"orderId\">order-123</field>\n    </event>\n    <event name=\"OrderShipped\">\n      <field name=\"orderId\">order-123</field>\n      <field name=\"shippedAt\">2024-01-15T10:00:00Z</field>\n    </event>\n  </given>\n  <when>\n    <command name=\"CancelOrder\">\n      <field name=\"orderId\">order-123</field>\n    </command>\n  </when>\n  <then type=\"error\" errorType=\"BusinessRuleViolation\">Cannot cancel an order that has already shipped</then>\n</scenario>'\n```\n\n---\n\n## Automation Scenarios\n\nFor slices where events trigger a processor to issue a command. Use the simpler **Given-Then** format:\n\n**Trigger Conditions Met** - Events cause processor to act\n- Given: All the events that have occurred (including the trigger events)\n- Then: The command the processor issues\n\n**Trigger Conditions Not Met** - Events don't cause action\n- Given: Events that don't meet the trigger condition\n- Then: noCommand (processor should not dispatch)\n\n### Automation Examples\n\n```bash\n# Payment received triggers shipment initiation\n# Given: OrderPlaced + PaymentReceived \u2192 Then: InitiateShipment command\neventmodeler add scenario --slice \"Auto Ship Order\" --xml '<scenario name=\"Payment triggers shipment\" description=\"Given an order has been placed and payment received, the system automatically initiates shipment\">\n  <given>\n    <event name=\"OrderPlaced\">\n      <field name=\"orderId\">order-123</field>\n      <field name=\"customerId\">cust-456</field>\n    </event>\n    <event name=\"PaymentReceived\">\n      <field name=\"orderId\">order-123</field>\n      <field name=\"amount\">99.99</field>\n    </event>\n  </given>\n  <then type=\"command\">\n    <command name=\"InitiateShipment\">\n      <field name=\"orderId\">order-123</field>\n      <field name=\"warehouseId\">wh-001</field>\n    </command>\n  </then>\n</scenario>'\n```\n\n```bash\n# Negative case - conditions not met, no command dispatched\neventmodeler add scenario --slice \"Auto Ship Order\" --xml '<scenario name=\"No shipment without payment\" description=\"Given only an order placed (no payment), the system should not initiate shipment\">\n  <given>\n    <event name=\"OrderPlaced\">\n      <field name=\"orderId\">order-123</field>\n      <field name=\"customerId\">cust-456</field>\n    </event>\n  </given>\n  <then type=\"noCommand\"/>\n</scenario>'\n```\n\n---\n\n## Read Model Assertions\n\nFor state-view slices, test that events project correctly to read models:\n\n```bash\neventmodeler add scenario --slice \"<slice-name>\" --xml '<scenario name=\"Order appears in summary\" description=\"After placing an order, it should be visible in the order summary with pending status\">\n  <then type=\"readModelAssertion\">\n    <read-model name=\"OrderSummary\">\n      <field name=\"orderId\">order-456</field>\n      <field name=\"status\">pending</field>\n    </read-model>\n  </then>\n</scenario>'\n```\n\n---\n\n## Scenario Types Summary\n\n| Slice Type | Format | Then Contains |\n|------------|--------|---------------|\n| State-Change | Given \u2192 When (Command) \u2192 Then | Events or Error |\n| Automation | Given (Events) \u2192 Then | Command or noCommand |\n| State-View | Given \u2192 Then | Read Model Assertion |\n\n## JSON Format Alternative\n\nYou can also use JSON format:\n\n**State-Change Scenario:**\n```bash\neventmodeler add scenario --slice \"<slice-name>\" --json '{\n  \"name\": \"Successfully place order\",\n  \"description\": \"A registered customer can place an order\",\n  \"given\": [\n    { \"event\": \"CustomerRegistered\", \"fieldValues\": { \"customerId\": \"cust-123\" } }\n  ],\n  \"when\": {\n    \"command\": \"PlaceOrder\",\n    \"commandFieldValues\": { \"customerId\": \"cust-123\", \"items\": [] }\n  },\n  \"then\": {\n    \"type\": \"events\",\n    \"events\": [\n      { \"event\": \"OrderPlaced\", \"fieldValues\": { \"orderId\": \"order-456\" } }\n    ]\n  }\n}'\n```\n\n**Automation Scenario (Given-Then format):**\n```bash\neventmodeler add scenario --slice \"<slice-name>\" --json '{\n  \"name\": \"Payment triggers shipment\",\n  \"description\": \"Given order placed and payment received, shipment is initiated\",\n  \"given\": [\n    { \"event\": \"OrderPlaced\", \"fieldValues\": { \"orderId\": \"order-123\" } },\n    { \"event\": \"PaymentReceived\", \"fieldValues\": { \"orderId\": \"order-123\", \"amount\": 99.99 } }\n  ],\n  \"then\": {\n    \"type\": \"command\",\n    \"command\": \"InitiateShipment\",\n    \"commandFieldValues\": { \"orderId\": \"order-123\" }\n  }\n}'\n```\n\n**Automation Scenario (negative case):**\n```bash\neventmodeler add scenario --slice \"<slice-name>\" --json '{\n  \"name\": \"No shipment without payment\",\n  \"description\": \"Given only order placed (no payment), no command dispatched\",\n  \"given\": [\n    { \"event\": \"OrderPlaced\", \"fieldValues\": { \"orderId\": \"order-123\" } }\n  ],\n  \"then\": {\n    \"type\": \"noCommand\"\n  }\n}'\n```\n\n## Best Practices\n\n1. **Write clear descriptions** - Explain why this scenario matters and what business rule it captures\n2. **Use realistic example values** - \"cust-123\" not \"string\", \"2024-01-15\" not \"date\"\n3. **Name scenarios descriptively** - \"Cannot cancel shipped order\" not \"Error case 1\"\n4. **Include all relevant fields** - Don't skip fields that matter for the scenario\n5. **Think about state** - What events need to exist for this scenario to make sense?\n6. **Cover the negative cases** - These often reveal missing business rules (use `noCommand` for automations)\n7. **Match format to slice type** - Use Given-When-Then for state-change, Given-Then for automation\n";