eventmodeler 0.4.7 → 0.5.0

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

@@ -2,4 +2,4 @@ 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";
+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), use element IDs with the `id:` prefix. This works with every command that accepts an element name \u2014 not just flows. See `eventmodeler guide explore` for the full details.\n\n```bash\n# Find element IDs via list commands\neventmodeler list events\n# <event id=\"abc12345-...\" name=\"OrderPlaced\" fields=\"4\"/>\n# <event id=\"def67890-...\" name=\"OrderPlaced\" fields=\"4\"/>  <!-- linked copy -->\n\n# Use ID prefix (first 8 chars is usually enough)\neventmodeler create flow --from \"id:abc12345\" --to \"OrderStatus\"\neventmodeler map fields --flow \"id:abc12345\u2192OrderStatus\" --xml '\n  <mapping from=\"orderId\" to=\"orderId\"/>\n'\n```\n\nThe CLI will tell you when names are ambiguous and show the IDs to choose from.\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";

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

@@ -133,47 +133,22 @@ 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), you'll need to use element IDs instead of names.
-
-### Finding Element 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
-# List events with their IDs
+# Find element IDs via list commands
 eventmodeler list events
-# Output:
-# <events>
-#   <event id="abc12345-..." name="OrderPlaced" fields="4"/>
-#   <event id="def67890-..." name="OrderPlaced" fields="4"/>  <!-- linked copy -->
-# </events>
-\`\`\`
-
-### Using IDs in Commands
+# <event id="abc12345-..." name="OrderPlaced" fields="4"/>
+# <event id="def67890-..." name="OrderPlaced" fields="4"/>  <!-- linked copy -->
 
-Prefix the ID (or ID prefix) with \`id:\`:
-
-\`\`\`bash
-# Create flow using ID prefix (first 8 characters is usually enough)
+# Use ID prefix (first 8 chars is usually enough)
 eventmodeler create flow --from "id:abc12345" --to "OrderStatus"
-
-# Map fields using ID prefix
 eventmodeler map fields --flow "id:abc12345→OrderStatus" --xml '
   <mapping from="orderId" to="orderId"/>
 '
 \`\`\`
 
-### When the CLI Finds Duplicates
-
-If you use a name that matches multiple elements, the CLI will show you the options:
-
-\`\`\`bash
-eventmodeler create flow --from "OrderPlaced" --to "OrderStatus"
-# Error: Multiple events found with name "OrderPlaced"
-# Please specify using the element ID:
-#   - "OrderPlaced" (id: abc12345-1234-5678-9abc-def012345678)
-#   - "OrderPlaced" (id: def67890-1234-5678-9abc-def012345678)
-#
-# Usage: eventmodeler create flow --from "id:abc12345" --to "OrderStatus"
-\`\`\`
+The CLI will tell you when names are ambiguous and show the IDs to choose from.
 
 ## Common Patterns
 

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

@@ -2,4 +2,4 @@ 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## 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";
+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";

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

@@ -201,6 +201,30 @@ 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:

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

@@ -2,4 +2,4 @@ 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\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";
+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

@@ -125,6 +125,8 @@ The \`--flow\` argument accepts:
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eventmodeler",
-  "version": "0.4.7",
+  "version": "0.5.0",
   "description": "CLI tool for event modeling - explore, design, and generate code from your event models",
   "type": "module",
   "bin": {