eventmodeler 0.3.4 → 0.3.6

package/dist/index.js

@@ -48,6 +48,9 @@ function getNamedArg(argList, ...names) {
     }
     return undefined;
 }
+function hasHelpFlag(argList) {
+    return argList.includes('-h') || argList.includes('--help');
+}
 function printHelp() {
     console.log(`
 eventmodeler - CLI tool for interacting with Event Model files
@@ -157,6 +160,7 @@ async function main() {
     let formatArg = null;
     let chapterArg = null;
     const filteredArgs = [];
+    let helpRequested = false;
     for (let i = 0; i < args.length; i++) {
         if (args[i] === '-f' || args[i] === '--file') {
             fileArg = args[++i];
@@ -167,18 +171,23 @@ async function main() {
         else if (args[i] === '--chapter') {
             chapterArg = args[++i];
         }
-        else if (args[i] === '-h' || args[i] === '--help') {
-            printHelp();
-            process.exit(0);
-        }
         else if (args[i] === '-v' || args[i] === '--version') {
             console.log(`eventmodeler ${VERSION}`);
             process.exit(0);
         }
+        else if (args[i] === '-h' || args[i] === '--help') {
+            helpRequested = true;
+        }
         else {
             filteredArgs.push(args[i]);
         }
     }
+    // Handle --help: if no command specified, show general help
+    // Otherwise let command-specific help handle it
+    if (helpRequested && filteredArgs.length === 0) {
+        printHelp();
+        process.exit(0);
+    }
     // Determine output format
     const format = formatArg === 'json' ? 'json'
         : formatArg === 'xml' ? 'xml'
@@ -195,6 +204,42 @@ async function main() {
     }
     // Handle diff and merge commands separately (they manage their own file loading)
     if (command === 'diff') {
+        if (helpRequested) {
+            console.log(`
+eventmodeler diff - Compare event model files semantically
+
+USAGE:
+  eventmodeler diff <file1> <file2> [--format text|xml|json]
+  eventmodeler diff <file> [--ref <gitref>] [--format text|xml|json]
+  eventmodeler diff --base <file> --compare <file> [--format text|xml|json]
+
+ARGUMENTS:
+  <file1> <file2>   Two files to compare
+  <file>            Single file to compare against git ref
+
+OPTIONS:
+  --ref <gitref>      Git reference to compare against (default: HEAD)
+  --base <file>       Base file (alternative syntax)
+  --compare <file>    Compare file (alternative syntax)
+  --format <format>   Output format: text (default), xml, or json
+
+OUTPUT:
+  Semantic differences between models:
+  - Added/removed/modified entities
+  - Field changes (with flag changes like isGenerated)
+  - Flow changes
+  - Scenario changes
+
+Unlike line-based diff, this understands event model structure.
+
+EXAMPLES:
+  eventmodeler diff model-v1.eventmodel model-v2.eventmodel
+  eventmodeler diff mymodel.eventmodel --ref HEAD~1
+  eventmodeler diff mymodel.eventmodel --ref main
+  eventmodeler diff model.eventmodel --format json
+`);
+            process.exit(0);
+        }
         const baseArg = getNamedArg(filteredArgs, '--base');
         const compareArg = getNamedArg(filteredArgs, '--compare');
         const refArg = getNamedArg(filteredArgs, '--ref');
@@ -223,9 +268,49 @@ async function main() {
         console.error('Usage: eventmodeler diff <file1> <file2>');
         console.error('       eventmodeler diff <file> [--ref <gitref>]');
         console.error('       eventmodeler diff --base <file> --compare <file>');
+        console.error('Run "eventmodeler diff --help" for more information.');
         process.exit(1);
     }
     if (command === 'merge') {
+        if (helpRequested) {
+            console.log(`
+eventmodeler merge - Three-way merge of event model files
+
+USAGE:
+  eventmodeler merge --base <file> --ours <file> --theirs <file> --output <file>
+
+OPTIONS:
+  --base <file>       Common ancestor file (required)
+  --ours <file>       Our version file (required)
+  --theirs <file>     Their version file (required)
+  --output <file>     Output file path (required unless --dry-run)
+  --strategy <s>      Auto-resolve conflicts: ours or theirs
+  --dry-run           Show result without writing file
+  --format xml|json   Output format for conflict reporting
+
+HOW IT WORKS:
+  Performs semantic three-way merge:
+  1. Identifies changes in "ours" vs base
+  2. Identifies changes in "theirs" vs base
+  3. Auto-merges non-conflicting changes
+  4. Reports conflicts for manual resolution
+
+CONFLICT RESOLUTION:
+  --strategy ours     Keep our changes when conflicts occur
+  --strategy theirs   Keep their changes when conflicts occur
+
+EXAMPLES:
+  # Standard merge
+  eventmodeler merge --base base.eventmodel --ours mine.eventmodel --theirs theirs.eventmodel --output merged.eventmodel
+
+  # Auto-resolve with our changes taking precedence
+  eventmodeler merge --base base.eventmodel --ours mine.eventmodel --theirs theirs.eventmodel --output merged.eventmodel --strategy ours
+
+  # Preview merge without writing
+  eventmodeler merge --base base.eventmodel --ours mine.eventmodel --theirs theirs.eventmodel --dry-run
+`);
+            process.exit(0);
+        }
         const baseArg = getNamedArg(filteredArgs, '--base');
         const oursArg = getNamedArg(filteredArgs, '--ours');
         const theirsArg = getNamedArg(filteredArgs, '--theirs');
@@ -237,6 +322,7 @@ async function main() {
             console.error('Options:');
             console.error('  --strategy ours|theirs    Auto-resolve conflicts');
             console.error('  --dry-run                 Show result without writing');
+            console.error('Run "eventmodeler merge --help" for more information.');
             process.exit(1);
         }
         if (!outputArg && !dryRun) {
@@ -257,16 +343,80 @@ async function main() {
     if (command === 'git') {
         const gitCommand = filteredArgs[1];
         const globalFlag = filteredArgs.includes('--global');
+        if (helpRequested && !gitCommand) {
+            console.log(`
+eventmodeler git - Git integration commands
+
+USAGE:
+  eventmodeler git <command> [options]
+
+COMMANDS:
+  setup    Configure git for semantic diff/merge of .eventmodel files
+  status   Show current git integration status
+
+Run "eventmodeler git <command> --help" for command-specific help.
+`);
+            process.exit(0);
+        }
         switch (gitCommand) {
             case 'setup':
+                if (helpRequested) {
+                    console.log(`
+eventmodeler git setup - Configure git for semantic diff/merge
+
+USAGE:
+  eventmodeler git setup [--global]
+
+OPTIONS:
+  --global   Configure globally (for all repositories)
+
+WHAT IT DOES:
+  1. Adds .gitattributes entry: *.eventmodel diff=eventmodel merge=eventmodel
+  2. Configures git diff driver for semantic comparison
+  3. Configures git merge driver for semantic merging
+
+After setup:
+  - "git diff" shows semantic differences for .eventmodel files
+  - "git merge" performs semantic merging
+  - Conflicts are reported at entity level, not line level
+
+LOCAL VS GLOBAL:
+  Without --global: Configures current repository only
+  With --global: Configures for all repositories (user-level)
+
+EXAMPLES:
+  eventmodeler git setup           # Configure current repo
+  eventmodeler git setup --global  # Configure globally
+`);
+                    process.exit(0);
+                }
                 gitSetup(globalFlag);
                 return;
             case 'status':
+                if (helpRequested) {
+                    console.log(`
+eventmodeler git status - Show git integration status
+
+USAGE:
+  eventmodeler git status
+
+OUTPUT:
+  Shows current configuration:
+  - Whether git drivers are configured
+  - Local vs global configuration status
+  - .gitattributes configuration status
+
+EXAMPLES:
+  eventmodeler git status
+`);
+                    process.exit(0);
+                }
                 gitStatus();
                 return;
             default:
                 console.error('Usage: eventmodeler git setup [--global]');
                 console.error('       eventmodeler git status');
+                console.error('Run "eventmodeler git --help" for more information.');
                 process.exit(1);
         }
     }
@@ -283,82 +433,461 @@ async function main() {
     const model = loadModel(filePath);
     switch (command) {
         case 'list':
+            if (helpRequested && !subcommand) {
+                console.log(`
+eventmodeler list - List entities in the event model
+
+USAGE:
+  eventmodeler list <type> [options]
+
+TYPES:
+  slices      List all slices (with optional --chapter filter)
+  events      List all events
+  commands    List all commands
+  chapters    List all chapters
+  aggregates  List all aggregates
+  actors      List all actors
+
+OPTIONS:
+  --chapter <name>    Filter slices by chapter (slices only)
+  --format xml|json   Output format (default: xml)
+
+EXAMPLES:
+  eventmodeler list slices
+  eventmodeler list slices --chapter "Order Management"
+  eventmodeler list events --format json
+
+Run "eventmodeler list <type> --help" for type-specific help.
+`);
+                process.exit(0);
+            }
             switch (subcommand) {
                 case 'slices':
+                    if (helpRequested) {
+                        console.log(`
+eventmodeler list slices - List all slices in the event model
+
+USAGE:
+  eventmodeler list slices [--chapter <name>] [--format xml|json]
+
+OPTIONS:
+  --chapter <name>    Filter by chapter name
+  --format <format>   Output format: xml (default) or json
+
+OUTPUT FIELDS:
+  name      Slice name
+  type      state-change | automation | state-view
+  status    created | in-progress | blocked | done
+  chapter   Parent chapter name
+
+EXAMPLES:
+  eventmodeler list slices
+  eventmodeler list slices --chapter "Order Management"
+  eventmodeler list slices --format json
+`);
+                        process.exit(0);
+                    }
                     listSlices(model, format, chapterArg ?? undefined);
                     break;
                 case 'events':
+                    if (helpRequested) {
+                        console.log(`
+eventmodeler list events - List all events in the event model
+
+USAGE:
+  eventmodeler list events [--format xml|json]
+
+OPTIONS:
+  --format <format>   Output format: xml (default) or json
+
+OUTPUT FIELDS:
+  name        Event name
+  aggregate   Parent aggregate name
+
+NOTE: Linked copies (events referencing a canonical original) are excluded.
+
+EXAMPLES:
+  eventmodeler list events
+  eventmodeler list events --format json
+`);
+                        process.exit(0);
+                    }
                     listEvents(model, format);
                     break;
                 case 'commands':
+                    if (helpRequested) {
+                        console.log(`
+eventmodeler list commands - List all commands in the event model
+
+USAGE:
+  eventmodeler list commands [--format xml|json]
+
+OPTIONS:
+  --format <format>   Output format: xml (default) or json
+
+OUTPUT FIELDS:
+  name        Command name
+  aggregate   Parent aggregate name
+
+EXAMPLES:
+  eventmodeler list commands
+  eventmodeler list commands --format json
+`);
+                        process.exit(0);
+                    }
                     listCommands(model, format);
                     break;
                 case 'chapters':
+                    if (helpRequested) {
+                        console.log(`
+eventmodeler list chapters - List all chapters in the event model
+
+USAGE:
+  eventmodeler list chapters [--format xml|json]
+
+OPTIONS:
+  --format <format>   Output format: xml (default) or json
+
+OUTPUT FIELDS:
+  name         Chapter name
+  sliceCount   Number of slices in chapter
+
+EXAMPLES:
+  eventmodeler list chapters
+  eventmodeler list chapters --format json
+`);
+                        process.exit(0);
+                    }
                     listChapters(model, format);
                     break;
                 case 'aggregates':
+                    if (helpRequested) {
+                        console.log(`
+eventmodeler list aggregates - List all aggregates in the event model
+
+USAGE:
+  eventmodeler list aggregates [--format xml|json]
+
+OPTIONS:
+  --format <format>   Output format: xml (default) or json
+
+OUTPUT FIELDS:
+  name          Aggregate name
+  eventCount    Number of events
+  commandCount  Number of commands
+
+EXAMPLES:
+  eventmodeler list aggregates
+  eventmodeler list aggregates --format json
+`);
+                        process.exit(0);
+                    }
                     listAggregates(model, format);
                     break;
                 case 'actors':
+                    if (helpRequested) {
+                        console.log(`
+eventmodeler list actors - List all actors in the event model
+
+USAGE:
+  eventmodeler list actors [--format xml|json]
+
+OPTIONS:
+  --format <format>   Output format: xml (default) or json
+
+OUTPUT FIELDS:
+  name          Actor name
+  screenCount   Number of screens
+
+EXAMPLES:
+  eventmodeler list actors
+  eventmodeler list actors --format json
+`);
+                        process.exit(0);
+                    }
                     listActors(model, format);
                     break;
                 default:
                     console.error(`Unknown list target: ${subcommand}`);
                     console.error('Valid targets: slices, events, commands, chapters, aggregates, actors');
+                    console.error('Run "eventmodeler list --help" for more information.');
                     process.exit(1);
             }
             break;
         case 'show':
+            if (helpRequested && !subcommand) {
+                console.log(`
+eventmodeler show - Show detailed information about entities
+
+USAGE:
+  eventmodeler show <type> <name> [options]
+
+TYPES:
+  slice                  Show slice with components and flows
+  event                  Show event with all fields
+  command                Show command with all fields
+  chapter                Show chapter with slices and dependencies
+  completeness           Show field mapping completeness for any element
+  model-completeness     Show completeness of all flows
+  aggregate-completeness Show if events have aggregate ID field
+  actor                  Show actor with screens
+
+OPTIONS:
+  --format xml|json   Output format (default: xml)
+
+EXAMPLES:
+  eventmodeler show slice "Place Order"
+  eventmodeler show event OrderPlaced
+  eventmodeler show completeness OrderSummary
+
+Run "eventmodeler show <type> --help" for type-specific help.
+`);
+                process.exit(0);
+            }
             switch (subcommand) {
                 case 'slice':
+                    if (helpRequested) {
+                        console.log(`
+eventmodeler show slice - Show detailed slice information
+
+USAGE:
+  eventmodeler show slice <name> [--format xml|json]
+
+ARGUMENTS:
+  <name>   Slice name (spaces allowed without quotes)
+
+OUTPUT INCLUDES:
+  - Slice type (state-change, automation, state-view)
+  - Status (created, in-progress, blocked, done)
+  - Components: screens, commands, events, read models, processors
+  - Each component's fields with types and flags
+  - Flow annotations and swimlane positions
+  - Inbound/outbound dependencies
+  - Scenarios (Given-When-Then specifications)
+
+EXAMPLES:
+  eventmodeler show slice "Place Order"
+  eventmodeler show slice Place Order
+  eventmodeler show slice "Place Order" --format json
+`);
+                        process.exit(0);
+                    }
                     if (!target) {
                         console.error('Usage: eventmodeler show slice <name>');
+                        console.error('Run "eventmodeler show slice --help" for more information.');
                         process.exit(1);
                     }
                     showSlice(model, target, format);
                     break;
                 case 'event':
+                    if (helpRequested) {
+                        console.log(`
+eventmodeler show event - Show detailed event information
+
+USAGE:
+  eventmodeler show event <name> [--format xml|json]
+
+ARGUMENTS:
+  <name>   Event name (spaces allowed without quotes)
+
+OUTPUT INCLUDES:
+  - Event name and aggregate
+  - All fields with:
+    - name: Field name
+    - type: UUID, String, Int, Long, Double, Decimal, Boolean, Date, DateTime, Custom
+    - isList: Whether field is an array
+    - isOptional: Whether field can be null
+    - isGenerated: Whether field is computed (not mapped from source)
+    - subfields: Nested fields for Custom types (recursive, with all flags)
+
+FIELD OUTPUT FORMAT (XML):
+  <field name="orderId" type="UUID"/>
+  <field name="total" type="Decimal" isGenerated="true"/>
+  <field name="items" type="Custom" isList="true">
+    <field name="productId" type="UUID"/>
+    <field name="lineTotal" type="Decimal" isGenerated="true"/>
+  </field>
+
+EXAMPLES:
+  eventmodeler show event OrderPlaced
+  eventmodeler show event "Order Placed" --format json
+`);
+                        process.exit(0);
+                    }
                     if (!target) {
                         console.error('Usage: eventmodeler show event <name>');
+                        console.error('Run "eventmodeler show event --help" for more information.');
                         process.exit(1);
                     }
                     showEvent(model, target, format);
                     break;
                 case 'command':
+                    if (helpRequested) {
+                        console.log(`
+eventmodeler show command - Show detailed command information
+
+USAGE:
+  eventmodeler show command <name> [--format xml|json]
+
+ARGUMENTS:
+  <name>   Command name (spaces allowed without quotes)
+
+OUTPUT INCLUDES:
+  - Command name and aggregate
+  - All fields with types, flags, and nested subfields
+
+EXAMPLES:
+  eventmodeler show command PlaceOrder
+  eventmodeler show command "Place Order" --format json
+`);
+                        process.exit(0);
+                    }
                     if (!target) {
                         console.error('Usage: eventmodeler show command <name>');
+                        console.error('Run "eventmodeler show command --help" for more information.');
                         process.exit(1);
                     }
                     showCommand(model, target, format);
                     break;
                 case 'chapter':
+                    if (helpRequested) {
+                        console.log(`
+eventmodeler show chapter - Show detailed chapter information
+
+USAGE:
+  eventmodeler show chapter <name> [--format xml|json]
+
+ARGUMENTS:
+  <name>   Chapter name
+
+OUTPUT INCLUDES:
+  - All slices in the chapter
+  - Flow graph showing internal dependencies
+  - External dependencies (inbound/outbound)
+
+EXAMPLES:
+  eventmodeler show chapter "Order Management"
+  eventmodeler show chapter "Order Management" --format json
+`);
+                        process.exit(0);
+                    }
                     if (!target) {
                         console.error('Usage: eventmodeler show chapter <name>');
+                        console.error('Run "eventmodeler show chapter --help" for more information.');
                         process.exit(1);
                     }
                     showChapter(model, target, format);
                     break;
                 case 'completeness':
+                    if (helpRequested) {
+                        console.log(`
+eventmodeler show completeness - Show field mapping completeness
+
+USAGE:
+  eventmodeler show completeness <name> [--format xml|json]
+
+ARGUMENTS:
+  <name>   Element name (command, event, read model, screen, or processor)
+
+OUTPUT INCLUDES:
+  - Total fields vs mapped fields
+  - List of unmapped fields needing attention
+  - Mapping sources for mapped fields
+
+IMPORTANT - GENERATED FIELDS:
+  Fields with isGenerated=true are EXCLUDED from completeness checks.
+  Generated fields are computed/synthesized values that don't need
+  source mappings (e.g., calculated totals, timestamps, derived data).
+
+EXAMPLES:
+  eventmodeler show completeness OrderSummary
+  eventmodeler show completeness "Order Summary" --format json
+`);
+                        process.exit(0);
+                    }
                     if (!target) {
                         console.error('Usage: eventmodeler show completeness <element-name>');
                         console.error('Searches: commands, events, read models, screens, processors');
+                        console.error('Run "eventmodeler show completeness --help" for more information.');
                         process.exit(1);
                     }
                     showCompleteness(model, target, format);
                     break;
                 case 'model-completeness':
+                    if (helpRequested) {
+                        console.log(`
+eventmodeler show model-completeness - Show completeness of all flows
+
+USAGE:
+  eventmodeler show model-completeness [--format xml|json]
+
+OUTPUT INCLUDES:
+  - Complete flows (all required fields mapped)
+  - Incomplete flows with missing mappings
+  - Overall completeness percentage
+
+NOTE: Generated fields (isGenerated=true) are excluded from checks.
+
+EXAMPLES:
+  eventmodeler show model-completeness
+  eventmodeler show model-completeness --format json
+`);
+                        process.exit(0);
+                    }
                     showModelCompleteness(model, format);
                     break;
                 case 'aggregate-completeness':
+                    if (helpRequested) {
+                        console.log(`
+eventmodeler show aggregate-completeness - Check aggregate ID field presence
+
+USAGE:
+  eventmodeler show aggregate-completeness <name> [--format xml|json]
+
+ARGUMENTS:
+  <name>   Aggregate name
+
+OUTPUT:
+  Lists all events in the aggregate and whether each has the
+  aggregate ID field (e.g., "orderId" for "Order" aggregate).
+
+EXAMPLES:
+  eventmodeler show aggregate-completeness Order
+  eventmodeler show aggregate-completeness "Order" --format json
+`);
+                        process.exit(0);
+                    }
                     if (!target) {
                         console.error('Usage: eventmodeler show aggregate-completeness <aggregate-name>');
+                        console.error('Run "eventmodeler show aggregate-completeness --help" for more information.');
                         process.exit(1);
                     }
                     showAggregateCompleteness(model, target, format);
                     break;
                 case 'actor':
+                    if (helpRequested) {
+                        console.log(`
+eventmodeler show actor - Show detailed actor information
+
+USAGE:
+  eventmodeler show actor <name> [--format xml|json]
+
+ARGUMENTS:
+  <name>   Actor name
+
+OUTPUT INCLUDES:
+  - Actor name
+  - All associated screens
+
+EXAMPLES:
+  eventmodeler show actor Customer
+  eventmodeler show actor "Admin User" --format json
+`);
+                        process.exit(0);
+                    }
                     if (!target) {
                         console.error('Usage: eventmodeler show actor <actor-name>');
+                        console.error('Run "eventmodeler show actor --help" for more information.');
                         process.exit(1);
                     }
                     showActor(model, target, format);
@@ -366,17 +895,73 @@ async function main() {
                 default:
                     console.error(`Unknown show target: ${subcommand}`);
                     console.error('Valid targets: slice, event, command, chapter, completeness, model-completeness, aggregate-completeness, actor');
+                    console.error('Run "eventmodeler show --help" for more information.');
                     process.exit(1);
             }
             break;
         case 'search':
+            if (helpRequested) {
+                console.log(`
+eventmodeler search - Search for entities by name
+
+USAGE:
+  eventmodeler search <term> [--format xml|json]
+
+ARGUMENTS:
+  <term>   Search term (case-insensitive partial match)
+
+OPTIONS:
+  --format <format>   Output format: xml (default) or json
+
+SEARCHES ACROSS:
+  - Slices
+  - Events
+  - Commands
+  - Read Models
+  - Screens
+  - Processors
+  - Chapters
+  - Aggregates
+  - Actors
+
+EXAMPLES:
+  eventmodeler search order
+  eventmodeler search "payment" --format json
+`);
+                process.exit(0);
+            }
             if (!subcommand) {
                 console.error('Usage: eventmodeler search <term>');
+                console.error('Run "eventmodeler search --help" for more information.');
                 process.exit(1);
             }
             search(model, subcommand, format);
             break;
         case 'mark': {
+            if (helpRequested) {
+                console.log(`
+eventmodeler mark - Mark a slice's status
+
+USAGE:
+  eventmodeler mark <slice-name> <status>
+
+ARGUMENTS:
+  <slice-name>   Slice name (can include spaces)
+  <status>       One of: created, in-progress, blocked, done
+
+STATUSES:
+  created      Initial state, not yet started
+  in-progress  Currently being worked on
+  blocked      Work paused due to dependency or issue
+  done         Completed
+
+EXAMPLES:
+  eventmodeler mark "Place Order" done
+  eventmodeler mark "Process Payment" in-progress
+  eventmodeler mark "Ship Order" blocked
+`);
+                process.exit(0);
+            }
             // mark <slice-name> <status> - status is last arg, slice name is everything before
             // Note: subcommand contains first part of slice name, remainingArgs has the rest
             const validStatuses = ['created', 'in-progress', 'blocked', 'done'];
@@ -385,6 +970,7 @@ async function main() {
             if (allArgs.length < 2 || !validStatuses.includes(lastArg)) {
                 console.error('Usage: eventmodeler mark <slice-name> <status>');
                 console.error('Valid statuses: created, in-progress, blocked, done');
+                console.error('Run "eventmodeler mark --help" for more information.');
                 process.exit(1);
             }
             const sliceName = allArgs.slice(0, -1).join(' ');
@@ -393,22 +979,145 @@ async function main() {
             break;
         }
         case 'summary':
+            if (helpRequested) {
+                console.log(`
+eventmodeler summary - Show model summary statistics
+
+USAGE:
+  eventmodeler summary [--format xml|json]
+
+OPTIONS:
+  --format <format>   Output format: xml (default) or json
+
+OUTPUT:
+  Aggregate statistics including:
+  - Total counts (slices, events, commands, read models, screens, etc.)
+  - Slices by type (state-change, automation, state-view)
+  - Slices by status (created, in-progress, blocked, done)
+  - Chapter summary
+
+EXAMPLES:
+  eventmodeler summary
+  eventmodeler summary --format json
+`);
+                process.exit(0);
+            }
             showModelSummary(model, format);
             break;
         case 'export':
+            if (helpRequested && !subcommand) {
+                console.log(`
+eventmodeler export - Export the model
+
+USAGE:
+  eventmodeler export <format>
+
+FORMATS:
+  json   Export entire model as JSON
+
+Run "eventmodeler export json --help" for detailed help.
+`);
+                process.exit(0);
+            }
             switch (subcommand) {
                 case 'json':
+                    if (helpRequested) {
+                        console.log(`
+eventmodeler export json - Export entire model as JSON
+
+USAGE:
+  eventmodeler export json
+
+OUTPUT:
+  Complete event model as JSON to stdout, including:
+  - All entities (slices, events, commands, read models, screens, etc.)
+  - All flows and field mappings
+  - All scenarios
+  - Metadata (chapters, aggregates, actors)
+
+EXAMPLES:
+  eventmodeler export json
+  eventmodeler export json > model.json
+  eventmodeler export json | jq '.events'
+`);
+                        process.exit(0);
+                    }
                     exportEventmodelToJson(model);
                     break;
                 default:
                     console.error(`Unknown export format: ${subcommand}`);
                     console.error('Valid formats: json');
+                    console.error('Run "eventmodeler export --help" for more information.');
                     process.exit(1);
             }
             break;
         case 'add':
+            if (helpRequested && !subcommand) {
+                console.log(`
+eventmodeler add - Add entities to the model
+
+USAGE:
+  eventmodeler add <type> [options]
+
+TYPES:
+  scenario   Add Given-When-Then scenario to a slice
+  field      Add field to command, event, read model, screen, or processor
+
+Run "eventmodeler add <type> --help" for type-specific help.
+`);
+                process.exit(0);
+            }
             switch (subcommand) {
                 case 'scenario': {
+                    if (helpRequested) {
+                        console.log(`
+eventmodeler add scenario - Add a scenario to a slice
+
+USAGE:
+  eventmodeler add scenario --slice <name> --json|--xml <data>
+
+OPTIONS:
+  --slice <name>   Target slice name (required)
+  --json <data>    Scenario in JSON format
+  --xml <data>     Scenario in XML format
+
+JSON FORMAT:
+  {
+    "name": "Scenario name",
+    "given": {                              // Optional: preconditions
+      "type": "events",
+      "events": ["EventName1", "EventName2"]
+    },
+    "when": {                               // Optional: trigger
+      "type": "command",
+      "command": "CommandName"
+    },
+    "then": {                               // Required: expected outcome
+      "type": "events",
+      "events": ["ExpectedEvent"]
+    }
+  }
+
+XML FORMAT:
+  <scenario name="Scenario name">
+    <given type="events">
+      <event>EventName1</event>
+    </given>
+    <when type="command">
+      <command>CommandName</command>
+    </when>
+    <then type="events">
+      <event>ExpectedEvent</event>
+    </then>
+  </scenario>
+
+EXAMPLES:
+  eventmodeler add scenario --slice "Place Order" --json '{"name": "Happy path", "then": {"type": "events", "events": ["OrderPlaced"]}}'
+
+  eventmodeler add scenario --slice "Place Order" --xml '<scenario name="Out of stock"><given type="events"><event>ProductOutOfStock</event></given><then type="events"><event>OrderRejected</event></then></scenario>'
+`);
+                        process.exit(0);
+                    }
                     const sliceArg = getNamedArg(filteredArgs, '--slice');
                     const jsonArg = getNamedArg(filteredArgs, '--json');
                     const xmlArg = getNamedArg(filteredArgs, '--xml');
@@ -416,17 +1125,114 @@ async function main() {
                     if (!sliceArg) {
                         console.error('Error: --slice is required');
                         console.error('Usage: eventmodeler add scenario --slice <name> --json|--xml <data>');
+                        console.error('Run "eventmodeler add scenario --help" for detailed format.');
                         process.exit(1);
                     }
                     if (!inputData) {
                         console.error('Error: --json or --xml is required');
                         console.error('Usage: eventmodeler add scenario --slice <name> --json|--xml <data>');
+                        console.error('Run "eventmodeler add scenario --help" for detailed format.');
                         process.exit(1);
                     }
                     addScenario(model, filePath, sliceArg, inputData);
                     break;
                 }
                 case 'field': {
+                    if (helpRequested) {
+                        console.log(`
+eventmodeler add field - Add a field to an entity
+
+USAGE:
+  eventmodeler add field --command|--event|--read-model|--screen|--processor <name> --json|--xml <data>
+
+OPTIONS:
+  --command <name>      Target command name
+  --event <name>        Target event name
+  --read-model <name>   Target read model name
+  --screen <name>       Target screen name
+  --processor <name>    Target processor name
+  --json <data>         Field definition in JSON format
+  --xml <data>          Field definition in XML format
+
+FIELD TYPES:
+  UUID, String, Int, Long, Double, Decimal, Boolean, Date, DateTime, Custom
+
+FIELD FLAGS (work on ALL fields including nested subfields):
+  isList       - Field contains multiple values (array)
+  isOptional   - Field may be null/missing
+  isGenerated  - Field is computed/synthesized, not mapped from source
+  isUserInput  - (Screen only) Field is entered by user
+
+JSON FORMAT:
+  Simple field:
+    {"name": "orderId", "type": "UUID"}
+
+  Field with flags:
+    {"name": "notes", "type": "String", "isOptional": true}
+    {"name": "tags", "type": "String", "isList": true}
+    {"name": "total", "type": "Decimal", "isGenerated": true}
+
+  Nested Custom field with subfields (ALL flags work on subfields):
+    {
+      "name": "lineItem",
+      "type": "Custom",
+      "subfields": [
+        {"name": "productId", "type": "UUID"},
+        {"name": "quantity", "type": "Int"},
+        {"name": "unitPrice", "type": "Decimal"},
+        {"name": "lineTotal", "type": "Decimal", "isGenerated": true}
+      ]
+    }
+
+  List of Custom with generated subfields:
+    {
+      "name": "items",
+      "type": "Custom",
+      "isList": true,
+      "subfields": [
+        {"name": "sku", "type": "String"},
+        {"name": "qty", "type": "Int"},
+        {"name": "calculatedPrice", "type": "Decimal", "isGenerated": true}
+      ]
+    }
+
+XML FORMAT:
+  Simple field:
+    <field name="orderId" type="UUID"/>
+
+  Field with flags:
+    <field name="notes" type="String" isOptional="true"/>
+    <field name="tags" type="String" isList="true"/>
+    <field name="total" type="Decimal" isGenerated="true"/>
+
+  Nested Custom field (ALL flags work on subfields):
+    <field name="lineItem" type="Custom">
+      <field name="productId" type="UUID"/>
+      <field name="quantity" type="Int"/>
+      <field name="unitPrice" type="Decimal"/>
+      <field name="lineTotal" type="Decimal" isGenerated="true"/>
+    </field>
+
+  List of Custom with flags on subfields:
+    <field name="items" type="Custom" isList="true">
+      <field name="sku" type="String"/>
+      <field name="qty" type="Int"/>
+      <field name="calculatedPrice" type="Decimal" isGenerated="true"/>
+      <field name="notes" type="String" isOptional="true"/>
+    </field>
+
+NOTES:
+  - Generated fields are excluded from completeness checks
+  - Custom type fields must have subfields defined
+  - Subfields support arbitrary nesting depth
+
+EXAMPLES:
+  eventmodeler add field --event OrderPlaced --json '{"name": "orderId", "type": "UUID"}'
+  eventmodeler add field --read-model OrderSummary --json '{"name": "totalWithTax", "type": "Decimal", "isGenerated": true}'
+  eventmodeler add field --event OrderPlaced --xml '<field name="item" type="Custom"><field name="price" type="Decimal"/><field name="tax" type="Decimal" isGenerated="true"/></field>'
+`);
+                        process.exit(0);
+                    }
                     const commandArg = getNamedArg(filteredArgs, '--command');
                     const eventArg = getNamedArg(filteredArgs, '--event');
                     const readModelArg = getNamedArg(filteredArgs, '--read-model');
@@ -438,6 +1244,7 @@ async function main() {
                     if (!inputData) {
                         console.error('Error: --json or --xml is required');
                         console.error('Usage: eventmodeler add field --command|--event|--read-model|--screen|--processor <name> --json|--xml <data>');
+                        console.error('Run "eventmodeler add field --help" for detailed format documentation.');
                         process.exit(1);
                     }
                     addField(model, filePath, { command: commandArg, event: eventArg, readModel: readModelArg, screen: screenArg, processor: processorArg }, inputData);
@@ -450,18 +1257,74 @@ async function main() {
             }
             break;
         case 'remove':
+            if (helpRequested && !subcommand) {
+                console.log(`
+eventmodeler remove - Remove entities from the model
+
+USAGE:
+  eventmodeler remove <type> [options]
+
+TYPES:
+  scenario   Remove a scenario from a slice
+  field      Remove a field from an entity
+
+Run "eventmodeler remove <type> --help" for type-specific help.
+`);
+                process.exit(0);
+            }
             switch (subcommand) {
                 case 'scenario': {
+                    if (helpRequested) {
+                        console.log(`
+eventmodeler remove scenario - Remove a scenario from a slice
+
+USAGE:
+  eventmodeler remove scenario <name> [--slice <slice-name>]
+
+ARGUMENTS:
+  <name>   Scenario name to remove
+
+OPTIONS:
+  --slice <name>   Limit search to specific slice (optional)
+
+EXAMPLES:
+  eventmodeler remove scenario "Happy path"
+  eventmodeler remove scenario "Edge case" --slice "Place Order"
+`);
+                        process.exit(0);
+                    }
                     const scenarioName = target;
                     const sliceArg = getNamedArg(filteredArgs, '--slice');
                     if (!scenarioName) {
                         console.error('Usage: eventmodeler remove scenario <name> [--slice <slice-name>]');
+                        console.error('Run "eventmodeler remove scenario --help" for more information.');
                         process.exit(1);
                     }
                     removeScenario(model, filePath, scenarioName, sliceArg);
                     break;
                 }
                 case 'field': {
+                    if (helpRequested) {
+                        console.log(`
+eventmodeler remove field - Remove a field from an entity
+
+USAGE:
+  eventmodeler remove field --command|--event|--read-model|--screen|--processor <name> --field <field-name>
+
+OPTIONS:
+  --command <name>      Target command name
+  --event <name>        Target event name
+  --read-model <name>   Target read model name
+  --screen <name>       Target screen name
+  --processor <name>    Target processor name
+  --field <name>        Field name to remove (required)
+
+EXAMPLES:
+  eventmodeler remove field --event OrderPlaced --field orderId
+  eventmodeler remove field --read-model "Order Summary" --field notes
+`);
+                        process.exit(0);
+                    }
                     const commandArg = getNamedArg(filteredArgs, '--command');
                     const eventArg = getNamedArg(filteredArgs, '--event');
                     const readModelArg = getNamedArg(filteredArgs, '--read-model');
@@ -471,6 +1334,7 @@ async function main() {
                     if (!fieldArg) {
                         console.error('Error: --field is required');
                         console.error('Usage: eventmodeler remove field --command|--event|--read-model|--screen|--processor <name> --field <field-name>');
+                        console.error('Run "eventmodeler remove field --help" for more information.');
                         process.exit(1);
                     }
                     removeField(model, filePath, { command: commandArg, event: eventArg, readModel: readModelArg, screen: screenArg, processor: processorArg }, fieldArg);
@@ -479,12 +1343,63 @@ async function main() {
                 default:
                     console.error(`Unknown remove target: ${subcommand}`);
                     console.error('Valid targets: scenario, field');
+                    console.error('Run "eventmodeler remove --help" for more information.');
                     process.exit(1);
             }
             break;
         case 'map':
+            if (helpRequested && !subcommand) {
+                console.log(`
+eventmodeler map - Set field mappings
+
+USAGE:
+  eventmodeler map <type> [options]
+
+TYPES:
+  fields   Set field mappings on a flow
+
+Run "eventmodeler map fields --help" for detailed help.
+`);
+                process.exit(0);
+            }
             switch (subcommand) {
                 case 'fields': {
+                    if (helpRequested) {
+                        console.log(`
+eventmodeler map fields - Set field mappings on a flow
+
+USAGE:
+  eventmodeler map fields --flow <source→target> --json|--xml <mappings>
+
+OPTIONS:
+  --flow <spec>   Flow as "SourceName→TargetName" (use → or ->)
+  --json <data>   Mappings in JSON format
+  --xml <data>    Mappings in XML format
+
+JSON FORMAT:
+  [
+    {"from": "sourceField", "to": "targetField"},
+    {"from": "amount", "to": "orderTotal"}
+  ]
+
+XML FORMAT:
+  <mappings>
+    <mapping from="sourceField" to="targetField"/>
+    <mapping from="amount" to="orderTotal"/>
+  </mappings>
+
+NOTES:
+  - Mappings define how fields flow from source to target
+  - Fields marked as isGenerated=true don't need mappings
+  - Use "show completeness" to check mapping status
+
+EXAMPLES:
+  eventmodeler map fields --flow "OrderPlaced→OrderSummary" --json '[{"from": "total", "to": "totalAmount"}]'
+
+  eventmodeler map fields --flow "OrderPlaced->OrderSummary" --xml '<mappings><mapping from="total" to="totalAmount"/></mappings>'
+`);
+                        process.exit(0);
+                    }
                     const flowArg = getNamedArg(filteredArgs, '--flow');
                     const jsonArg = getNamedArg(filteredArgs, '--json');
                     const xmlArg = getNamedArg(filteredArgs, '--xml');
@@ -492,11 +1407,13 @@ async function main() {
                     if (!flowArg) {
                         console.error('Error: --flow is required');
                         console.error('Usage: eventmodeler map fields --flow <source→target> --json|--xml <mappings>');
+                        console.error('Run "eventmodeler map fields --help" for detailed format.');
                         process.exit(1);
                     }
                     if (!inputData) {
                         console.error('Error: --json or --xml is required');
                         console.error('Usage: eventmodeler map fields --flow <source→target> --json|--xml <mappings>');
+                        console.error('Run "eventmodeler map fields --help" for detailed format.');
                         process.exit(1);
                     }
                     mapFields(model, filePath, flowArg, inputData);
@@ -505,12 +1422,70 @@ async function main() {
                 default:
                     console.error(`Unknown map target: ${subcommand}`);
                     console.error('Valid targets: fields');
+                    console.error('Run "eventmodeler map --help" for more information.');
                     process.exit(1);
             }
             break;
         case 'update':
+            if (helpRequested && !subcommand) {
+                console.log(`
+eventmodeler update - Update entities in the model
+
+USAGE:
+  eventmodeler update <type> [options]
+
+TYPES:
+  field   Update field properties
+
+Run "eventmodeler update field --help" for detailed help.
+`);
+                process.exit(0);
+            }
             switch (subcommand) {
                 case 'field': {
+                    if (helpRequested) {
+                        console.log(`
+eventmodeler update field - Update field properties
+
+USAGE:
+  eventmodeler update field --command|--event|--read-model|--screen|--processor <name> --field <field-name> [updates]
+
+TARGET OPTIONS (one required):
+  --command <name>      Target command
+  --event <name>        Target event
+  --read-model <name>   Target read model
+  --screen <name>       Target screen
+  --processor <name>    Target processor
+
+REQUIRED:
+  --field <name>        Field to update
+
+UPDATE OPTIONS (at least one required):
+  --optional true|false    Set isOptional flag
+  --generated true|false   Set isGenerated flag
+  --user-input true|false  Set isUserInput flag (screen only)
+  --type <type>            Change field type
+
+FIELD FLAGS EXPLAINED:
+  isOptional    Field may be null/missing
+  isGenerated   Field is computed, excluded from completeness checks
+  isUserInput   (Screen only) Field entered by user vs displayed
+
+EXAMPLES:
+  # Mark field as optional
+  eventmodeler update field --read-model OrderSummary --field notes --optional true
+
+  # Mark field as generated (computed value, no mapping needed)
+  eventmodeler update field --read-model OrderSummary --field totalWithTax --generated true
+
+  # Mark screen field as user input
+  eventmodeler update field --screen "Order Form" --field quantity --user-input true
+
+  # Change field type
+  eventmodeler update field --event OrderPlaced --field amount --type Decimal
+`);
+                        process.exit(0);
+                    }
                     const commandArg = getNamedArg(filteredArgs, '--command');
                     const eventArg = getNamedArg(filteredArgs, '--event');
                     const readModelArg = getNamedArg(filteredArgs, '--read-model');
@@ -524,6 +1499,7 @@ async function main() {
                     if (!fieldArg) {
                         console.error('Error: --field is required');
                         console.error('Usage: eventmodeler update field --command|--event|--read-model|--screen|--processor <name> --field <field-name> [--optional true|false] [--generated true|false] [--user-input true|false (screen only)]');
+                        console.error('Run "eventmodeler update field --help" for detailed options.');
                         process.exit(1);
                     }
                     // --user-input is only valid for screens
@@ -546,6 +1522,7 @@ async function main() {
                     }
                     if (Object.keys(updates).length === 0) {
                         console.error('Error: Must specify at least one update (--optional, --generated, --user-input, or --type)');
+                        console.error('Run "eventmodeler update field --help" for available options.');
                         process.exit(1);
                     }
                     updateField(model, filePath, { command: commandArg, event: eventArg, readModel: readModelArg, screen: screenArg, processor: processorArg }, fieldArg, updates);
@@ -554,48 +1531,294 @@ async function main() {
                 default:
                     console.error(`Unknown update target: ${subcommand}`);
                     console.error('Valid targets: field');
+                    console.error('Run "eventmodeler update --help" for more information.');
                     process.exit(1);
             }
             break;
         case 'create':
+            if (helpRequested && !subcommand) {
+                console.log(`
+eventmodeler create - Create new slices and flows
+
+USAGE:
+  eventmodeler create <type> [options]
+
+TYPES:
+  state-change-slice   Create Screen → Command → Event slice
+  automation-slice     Create ReadModel → Processor → Command → Event slice
+  state-view-slice     Create ReadModel-only slice
+  flow                 Create flow between elements
+
+Run "eventmodeler create <type> --help" for type-specific help.
+`);
+                process.exit(0);
+            }
             switch (subcommand) {
                 case 'state-change-slice': {
+                    if (helpRequested) {
+                        console.log(`
+eventmodeler create state-change-slice - Create a state-change slice
+
+A state-change slice represents user action: Screen → Command → Event
+
+USAGE:
+  eventmodeler create state-change-slice --xml <data>
+
+XML FORMAT:
+  <state-change-slice name="Slice Name" [after="Slice Name"] [before="Slice Name"]>
+    <screen name="Screen Name" actor="Actor Name">
+      <field name="fieldName" type="Type" [flags]/>
+    </screen>
+    <command name="CommandName">
+      <field name="fieldName" type="Type" [flags]/>
+    </command>
+    <event name="EventName">
+      <field name="fieldName" type="Type" [flags]/>
+    </event>
+  </state-change-slice>
+
+POSITIONING (IMPORTANT):
+  after="Slice Name"   Place this slice immediately after the named slice
+  before="Slice Name"  Place this slice immediately before the named slice
+                       (shifts existing slices to the right)
+
+  If neither is specified, the slice is placed at the rightmost position.
+  Use "eventmodeler list slices" to see existing slice names for positioning.
+
+FIELD TYPES:
+  UUID, String, Int, Long, Double, Decimal, Boolean, Date, DateTime, Custom
+
+FIELD FLAGS (work on ALL fields and nested subfields):
+  isList="true"       Array/list of values
+  isOptional="true"   Nullable field
+  isGenerated="true"  Computed field (excluded from mapping completeness)
+  isUserInput="true"  User-entered field (screen fields only)
+
+NESTED CUSTOM FIELDS:
+  <field name="address" type="Custom">
+    <field name="street" type="String"/>
+    <field name="city" type="String"/>
+    <field name="formattedFull" type="String" isGenerated="true"/>
+  </field>
+
+EXAMPLES:
+  # Create slice at the end (default)
+  eventmodeler create state-change-slice --xml '
+    <state-change-slice name="Place Order">
+      <screen name="Order Form" actor="Customer">
+        <field name="productId" type="UUID" isUserInput="true"/>
+      </screen>
+      <command name="PlaceOrder">
+        <field name="productId" type="UUID"/>
+      </command>
+      <event name="OrderPlaced">
+        <field name="orderId" type="UUID"/>
+        <field name="productId" type="UUID"/>
+      </event>
+    </state-change-slice>'
+
+  # Create slice after an existing slice
+  eventmodeler create state-change-slice --xml '
+    <state-change-slice name="Confirm Order" after="Place Order">
+      ...
+    </state-change-slice>'
+
+  # Create slice before an existing slice (shifts others right)
+  eventmodeler create state-change-slice --xml '
+    <state-change-slice name="Review Cart" before="Place Order">
+      ...
+    </state-change-slice>'
+`);
+                        process.exit(0);
+                    }
                     const xmlArg = getNamedArg(filteredArgs, '--xml');
                     if (!xmlArg) {
                         console.error('Error: --xml is required');
                         console.error('Usage: eventmodeler create state-change-slice --xml \'<state-change-slice>...</state-change-slice>\'');
+                        console.error('Run "eventmodeler create state-change-slice --help" for detailed format.');
                         process.exit(1);
                     }
                     createStateChangeSlice(model, filePath, xmlArg);
                     break;
                 }
                 case 'automation-slice': {
+                    if (helpRequested) {
+                        console.log(`
+eventmodeler create automation-slice - Create an automation slice
+
+An automation slice represents system automation: ReadModel → Processor → Command → Event
+
+USAGE:
+  eventmodeler create automation-slice --xml <data>
+
+XML FORMAT:
+  <automation-slice name="Slice Name" [after="Slice Name"] [before="Slice Name"]>
+    <read-model name="ReadModelName">
+      <field name="fieldName" type="Type" [flags]/>
+    </read-model>
+    <processor name="ProcessorName">
+      <field name="fieldName" type="Type" [flags]/>
+    </processor>
+    <command name="CommandName">
+      <field name="fieldName" type="Type" [flags]/>
+    </command>
+    <event name="EventName">
+      <field name="fieldName" type="Type" [flags]/>
+    </event>
+  </automation-slice>
+
+POSITIONING (IMPORTANT):
+  after="Slice Name"   Place this slice immediately after the named slice
+  before="Slice Name"  Place this slice immediately before the named slice
+                       (shifts existing slices to the right)
+
+  If neither is specified, the slice is placed at the rightmost position.
+  Use "eventmodeler list slices" to see existing slice names for positioning.
+
+FIELD TYPES:
+  UUID, String, Int, Long, Double, Decimal, Boolean, Date, DateTime, Custom
+
+FIELD FLAGS (work on ALL fields and nested subfields):
+  isList="true"       Array/list of values
+  isOptional="true"   Nullable field
+  isGenerated="true"  Computed field (excluded from mapping completeness)
+
+EXAMPLES:
+  # Create automation slice after "Place Order" slice
+  eventmodeler create automation-slice --xml '
+    <automation-slice name="Auto-ship Order" after="Place Order">
+      <read-model name="OrderReadyForShipment">
+        <field name="orderId" type="UUID"/>
+        <field name="shippingAddress" type="String"/>
+      </read-model>
+      <processor name="ShipmentScheduler">
+        <field name="orderId" type="UUID"/>
+      </processor>
+      <command name="ScheduleShipment">
+        <field name="orderId" type="UUID"/>
+      </command>
+      <event name="ShipmentScheduled">
+        <field name="shipmentId" type="UUID" isGenerated="true"/>
+        <field name="orderId" type="UUID"/>
+        <field name="scheduledAt" type="DateTime" isGenerated="true"/>
+      </event>
+    </automation-slice>'
+
+  # Create automation slice before another slice
+  eventmodeler create automation-slice --xml '
+    <automation-slice name="Validate Inventory" before="Auto-ship Order">
+      ...
+    </automation-slice>'
+`);
+                        process.exit(0);
+                    }
                     const xmlArg = getNamedArg(filteredArgs, '--xml');
                     if (!xmlArg) {
                         console.error('Error: --xml is required');
                         console.error('Usage: eventmodeler create automation-slice --xml \'<automation-slice>...</automation-slice>\'');
+                        console.error('Run "eventmodeler create automation-slice --help" for detailed format.');
                         process.exit(1);
                     }
                     createAutomationSlice(model, filePath, xmlArg);
                     break;
                 }
                 case 'state-view-slice': {
+                    if (helpRequested) {
+                        console.log(`
+eventmodeler create state-view-slice - Create a state-view slice
+
+A state-view slice represents a read model for displaying data.
+
+USAGE:
+  eventmodeler create state-view-slice --xml <data>
+
+XML FORMAT:
+  <state-view-slice name="Slice Name" [after="Slice Name"] [before="Slice Name"]>
+    <read-model name="ReadModelName">
+      <field name="fieldName" type="Type" [flags]/>
+    </read-model>
+  </state-view-slice>
+
+POSITIONING (IMPORTANT):
+  after="Slice Name"   Place this slice immediately after the named slice
+  before="Slice Name"  Place this slice immediately before the named slice
+                       (shifts existing slices to the right)
+
+  If neither is specified, the slice is placed at the rightmost position.
+  Use "eventmodeler list slices" to see existing slice names for positioning.
+
+FIELD TYPES:
+  UUID, String, Int, Long, Double, Decimal, Boolean, Date, DateTime, Custom
+
+FIELD FLAGS (work on ALL fields and nested subfields):
+  isList="true"       Array/list of values
+  isOptional="true"   Nullable field
+  isGenerated="true"  Computed/aggregated field (common for dashboards)
+
+EXAMPLES:
+  # Create state-view slice after "Place Order" slice
+  eventmodeler create state-view-slice --xml '
+    <state-view-slice name="Order Dashboard" after="Place Order">
+      <read-model name="OrderDashboard">
+        <field name="totalOrders" type="Int" isGenerated="true"/>
+        <field name="totalRevenue" type="Decimal" isGenerated="true"/>
+        <field name="averageOrderValue" type="Decimal" isGenerated="true"/>
+        <field name="recentOrders" type="Custom" isList="true">
+          <field name="orderId" type="UUID"/>
+          <field name="total" type="Decimal"/>
+          <field name="status" type="String"/>
+        </field>
+      </read-model>
+    </state-view-slice>'
+
+  # Create state-view slice before another slice
+  eventmodeler create state-view-slice --xml '
+    <state-view-slice name="Customer Summary" before="Order Dashboard">
+      ...
+    </state-view-slice>'
+`);
+                        process.exit(0);
+                    }
                     const xmlArg = getNamedArg(filteredArgs, '--xml');
                     if (!xmlArg) {
                         console.error('Error: --xml is required');
                         console.error('Usage: eventmodeler create state-view-slice --xml \'<state-view-slice>...</state-view-slice>\'');
+                        console.error('Run "eventmodeler create state-view-slice --help" for detailed format.');
                         process.exit(1);
                     }
                     createStateViewSlice(model, filePath, xmlArg);
                     break;
                 }
                 case 'flow': {
+                    if (helpRequested) {
+                        console.log(`
+eventmodeler create flow - Create a flow between elements
+
+USAGE:
+  eventmodeler create flow --from <source> --to <target>
+
+OPTIONS:
+  --from <name>   Source element name (required)
+  --to <name>     Target element name (required)
+
+VALID FLOW TYPES:
+  Event → ReadModel       Event data projects into read model
+  ReadModel → Screen      Read model provides data to UI
+  ReadModel → Processor   Read model triggers automation
+
+EXAMPLES:
+  eventmodeler create flow --from OrderPlaced --to OrderSummary
+  eventmodeler create flow --from "Order Summary" --to "Order Dashboard Screen"
+  eventmodeler create flow --from OrderReadyForShipment --to ShipmentProcessor
+`);
+                        process.exit(0);
+                    }
                     const fromArg = getNamedArg(filteredArgs, '--from');
                     const toArg = getNamedArg(filteredArgs, '--to');
                     if (!fromArg || !toArg) {
                         console.error('Error: --from and --to are required');
                         console.error('Usage: eventmodeler create flow --from <source> --to <target>');
-                        console.error('Valid flows: Event→ReadModel, ReadModel→Screen, ReadModel→Processor');
+                        console.error('Run "eventmodeler create flow --help" for more information.');
                         process.exit(1);
                     }
                     createFlow(model, filePath, fromArg, toArg);
@@ -604,16 +1827,61 @@ async function main() {
                 default:
                     console.error(`Unknown create target: ${subcommand}`);
                     console.error('Valid targets: state-change-slice, automation-slice, state-view-slice, flow');
+                    console.error('Run "eventmodeler create --help" for more information.');
                     process.exit(1);
             }
             break;
         case 'codegen':
+            if (helpRequested && !subcommand) {
+                console.log(`
+eventmodeler codegen - Generate code-ready output
+
+USAGE:
+  eventmodeler codegen <type> [options]
+
+TYPES:
+  slice   Generate comprehensive JSON for a slice
+
+Run "eventmodeler codegen slice --help" for detailed help.
+`);
+                process.exit(0);
+            }
             switch (subcommand) {
                 case 'slice': {
+                    if (helpRequested) {
+                        console.log(`
+eventmodeler codegen slice - Generate code-ready JSON for a slice
+
+USAGE:
+  eventmodeler codegen slice <name>
+
+ARGUMENTS:
+  <name>   Slice name
+
+OUTPUT:
+  Comprehensive JSON including:
+  - Slice metadata (name, type, chapter, aggregate)
+  - All components with full field definitions
+    - Fields include: name, type, isList, isOptional, isGenerated
+    - Nested subfields for Custom types (all flags preserved)
+  - Field mappings between components
+  - Scenarios (Given-When-Then specifications)
+  - Dependencies (inbound/outbound flows)
+
+This output is designed for code generation tools and includes
+all information needed to generate implementation code.
+
+EXAMPLES:
+  eventmodeler codegen slice "Place Order"
+  eventmodeler codegen slice PlaceOrder > slice.json
+`);
+                        process.exit(0);
+                    }
                     const sliceName = filteredArgs[2];
                     if (!sliceName) {
                         console.error('Error: slice name is required');
                         console.error('Usage: eventmodeler codegen slice <name>');
+                        console.error('Run "eventmodeler codegen slice --help" for more information.');
                         process.exit(1);
                     }
                     codegenSlice(model, sliceName);
@@ -622,6 +1890,7 @@ async function main() {
                 default:
                     console.error(`Unknown codegen target: ${subcommand}`);
                     console.error('Valid targets: slice');
+                    console.error('Run "eventmodeler codegen --help" for more information.');
                     process.exit(1);
             }
             break;