Document sortOptions and help option ordering

Author: stalep

content/docs/aesh/command-definition.md

@@ -27,6 +27,7 @@ The `@CommandDefinition` annotation is used to define a command class.
 | `activator` | `Class<? extends CommandActivator>` | `NullCommandActivator.class` | Activator to check if command is available |
 | `defaultValueProvider` | `Class<? extends DefaultValueProvider>` | `NullDefaultValueProvider.class` | Dynamic default value resolver |
 | `stopAtFirstPositional` | `boolean` | `false` | Stop option parsing after the first positional argument |
+| `sortOptions` | `boolean` | `false` | Sort help options alphabetically by name (after explicit option order) |
 | `helpUrl` | `String` | `""` | URL to documentation (shown in `--help` output) |
 | `helpGroup` | `String` | `""` | Group heading when listed as a subcommand in parent's help |
 | `helpSectionProvider` | `Class<? extends HelpSectionProvider>` | `NullHelpSectionProvider.class` | Provider for dynamic help sections |
@@ -176,6 +177,43 @@ With the command above:
 
 Note that `--help` (and `--version`) before the first positional still work normally when `generateHelp = true`. Only tokens after the first positional are treated as passthrough arguments.
 
+## Option Ordering in Help
+
+Use `sortOptions` to control how options are ordered in help output:
+
+- `sortOptions = false` (default): options are ordered by explicit option `order`, then declaration order
+- `sortOptions = true`: options are ordered by explicit option `order`, then alphabetical name
+
+```java
+@CommandDefinition(
+    name = "build",
+    description = "Build project",
+    sortOptions = true,
+    generateHelp = true
+)
+public class BuildCommand implements Command<CommandInvocation> {
+
+    @Option(description = "Always first", order = 10)
+    private boolean ci;
+
+    @Option(description = "Build profile", order = 20)
+    private String profile;
+
+    @Option(description = "Clean output")
+    private boolean clean;
+
+    @Option(description = "Verbose output")
+    private boolean verbose;
+
+    @Override
+    public CommandResult execute(CommandInvocation invocation) {
+        return CommandResult.SUCCESS;
+    }
+}
+```
+
+The `order` attribute is defined on `@Option`, `@OptionList`, and `@OptionGroup`.
+
 ### CommandInvocation
 
 Provides access to:

content/docs/aesh/group-commands.md

@@ -38,6 +38,7 @@ public class GitCommand implements GroupCommand<CommandInvocation> {
 | `groupCommands` | `Class[]` | `{}` | Array of subcommand classes |
 | `generateHelp` | `boolean` | `false` | Auto-generate `--help` option |
 | `aliases` | `String[]` | `{}` | Alternative names for the group |
+| `sortOptions` | `boolean` | `false` | Sort help options alphabetically by name (after explicit option order) |
 | `helpGroup` | `String` | `""` | Group heading when listed as a subcommand in parent's help |
 | `helpSectionProvider` | `Class<? extends HelpSectionProvider>` | `NullHelpSectionProvider.class` | Provider for dynamic help sections |
 

content/docs/aesh/option-groups.md

@@ -24,6 +24,7 @@ The `@OptionGroup` annotation defines key=value pair options collected into a `M
 | `renderer` | `Class<? extends OptionRenderer>` | `NullOptionRenderer.class` | Custom renderer |
 | `parser` | `Class<? extends OptionParser>` | `AeshOptionParser.class` | Custom parser |
 | `visibility` | `OptionVisibility` | `BRIEF` | Controls help and completion visibility (see [Options - Visibility Levels](../options#visibility-levels)) |
+| `order` | `int` | `Integer.MAX_VALUE` | Explicit help-order position (see [Options - Help Option Ordering](../options#help-option-ordering)) |
 
 ## Basic Example
 

content/docs/aesh/option-lists.md

@@ -28,6 +28,7 @@ The `@OptionList` annotation defines options that accept multiple values separat
 | `helpGroup` | `String` | `""` | Group heading for this option in help output (see [Options - Help Grouping](../options#help-grouping)) |
 | `exclusiveWith` | `String[]` | `{}` | Names of mutually exclusive options (see [Options - Mutually Exclusive Options](../options#mutually-exclusive-options)) |
 | `visibility` | `OptionVisibility` | `BRIEF` | Controls help and completion visibility (see [Options - Visibility Levels](../options#visibility-levels)) |
+| `order` | `int` | `Integer.MAX_VALUE` | Explicit help-order position (see [Options - Help Option Ordering](../options#help-option-ordering)) |
 
 ## Basic Example
 

content/docs/aesh/options.md

@@ -36,6 +36,7 @@ The `@Option` annotation defines command-line options (flags with values).
 | `allowedValues` | `String[]` | `{}` | Restricts option to a fixed set of valid values |
 | `exclusiveWith` | `String[]` | `{}` | Names of mutually exclusive options (without `--` prefix) |
 | `visibility` | `OptionVisibility` | `BRIEF` | Controls help and completion visibility (`BRIEF`, `FULL`, `HIDDEN`) |
+| `order` | `int` | `Integer.MAX_VALUE` | Explicit help-order position (lower values appear first) |
 | `descriptionUrl` | `String` | `""` | URL for option documentation (clickable in supported terminals) |
 | `url` | `boolean` | `false` | Treat option value as a URL (rendered as clickable link) |
 
@@ -543,6 +544,27 @@ ProcessedOptionBuilder.builder()
         .build();
 ```
 
+## Help Option Ordering
+
+Use `order` on options to explicitly control help output order:
+
+```java
+@Option(description = "Always first", order = 10)
+private boolean ci;
+
+@Option(description = "Shown after --ci", order = 20)
+private String profile;
+```
+
+Options are ordered by:
+
+1. `order` (lower first)
+2. Then by command-level `sortOptions` behavior:
+   - `sortOptions = false` (default): declaration order
+   - `sortOptions = true`: alphabetical by option name
+
+`order` also works on `@OptionList` and `@OptionGroup`.
+
 ## Mutually Exclusive Options
 
 The `exclusiveWith` property declares that two or more options cannot be used together. If a user provides both, a `MutuallyExclusiveOptionException` is thrown during parsing.