updated docs with option visiblity levels

Author: stalep

content/docs/aesh/command-definition.md

@@ -28,6 +28,8 @@ The `@CommandDefinition` annotation is used to define a command class.
 | `defaultValueProvider` | `Class<? extends DefaultValueProvider>` | `NullDefaultValueProvider.class` | Dynamic default value resolver |
 | `stopAtFirstPositional` | `boolean` | `false` | Stop option parsing after the first positional argument |
 | `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 |
 
 ## Example
 
@@ -182,3 +184,142 @@ Provides access to:
 - `stop()` - Stop the console
 - `getShell()` - Access the shell
 - `getHelpInfo(String)` - Get help text
+
+## Help Group for Subcommands
+
+The `helpGroup` property on `@CommandDefinition` (and `@GroupCommandDefinition`) controls how a subcommand appears in its parent's help output. Subcommands with the same `helpGroup` value are displayed together under that heading.
+
+### Basic Usage
+
+```java
+@GroupCommandDefinition(
+    name = "cli",
+    description = "My CLI tool",
+    generateHelp = true,
+    groupCommands = {
+        BuildCommand.class, TestCommand.class,
+        InstallCommand.class, PublishCommand.class,
+        InfoCommand.class, VersionCommand.class
+    }
+)
+public class CliCommand implements GroupCommand<CommandInvocation> {
+    @Override
+    public CommandResult execute(CommandInvocation invocation) {
+        return CommandResult.SUCCESS;
+    }
+}
+
+@CommandDefinition(name = "build", description = "Build the project", helpGroup = "Build")
+public class BuildCommand implements Command<CommandInvocation> { /* ... */ }
+
+@CommandDefinition(name = "test", description = "Run tests", helpGroup = "Build")
+public class TestCommand implements Command<CommandInvocation> { /* ... */ }
+
+@CommandDefinition(name = "install", description = "Install dependencies", helpGroup = "Publish")
+public class InstallCommand implements Command<CommandInvocation> { /* ... */ }
+
+@CommandDefinition(name = "publish", description = "Publish package", helpGroup = "Publish")
+public class PublishCommand implements Command<CommandInvocation> { /* ... */ }
+
+@CommandDefinition(name = "info", description = "Show project info")
+public class InfoCommand implements Command<CommandInvocation> { /* ... */ }
+
+@CommandDefinition(name = "version", description = "Show version")
+public class VersionCommand implements Command<CommandInvocation> { /* ... */ }
+```
+
+Help output:
+```
+Usage: cli [<options>]
+My CLI tool
+
+Build:
+    build     Build the project
+    test      Run tests
+
+Publish:
+    install   Install dependencies
+    publish   Publish package
+
+Other:
+    info      Show project info
+    version   Show version
+```
+
+### How It Works
+
+1. Subcommands with the same `helpGroup` value are grouped under that heading
+2. Named groups appear first, in the order their first subcommand was defined
+3. Subcommands without a `helpGroup` appear under a default heading
+4. If all subcommands have a `helpGroup`, there is no default group
+
+This is separate from the `helpGroup` property on `@Option`, which groups options within a single command's help output. See [Options - Help Grouping](/docs/aesh/options#help-grouping).
+
+## Help Section Provider
+
+The `helpSectionProvider` property lets you dynamically add sections to a command's help output at render time. This is useful for showing external plugins, aliases, or dynamically discovered commands without statically defining them.
+
+### Implementing a Provider
+
+Create a class that implements `HelpSectionProvider`:
+
+```java
+public class PluginHelpProvider implements HelpSectionProvider {
+
+    @Override
+    public Map<String, List<HelpEntry>> getAdditionalSections() {
+        Map<String, List<HelpEntry>> sections = new LinkedHashMap<>();
+
+        // Discover plugins at runtime
+        List<HelpEntry> plugins = new ArrayList<>();
+        plugins.add(new HelpEntry("docker", "Docker integration plugin"));
+        plugins.add(new HelpEntry("k8s", "Kubernetes deployment plugin"));
+        sections.put("Plugins", plugins);
+
+        return sections;
+    }
+}
+```
+
+### Registering the Provider
+
+```java
+@GroupCommandDefinition(
+    name = "app",
+    description = "My application",
+    generateHelp = true,
+    groupCommands = {RunCommand.class, BuildCommand.class},
+    helpSectionProvider = PluginHelpProvider.class
+)
+public class AppCommand implements GroupCommand<CommandInvocation> {
+    @Override
+    public CommandResult execute(CommandInvocation invocation) {
+        return CommandResult.SUCCESS;
+    }
+}
+```
+
+Help output:
+```
+Usage: app [<options>]
+My application
+
+app commands:
+    run       Run the application
+    build     Build the project
+
+Plugins:
+    docker    Docker integration plugin
+    k8s       Kubernetes deployment plugin
+```
+
+### Merging with helpGroup
+
+If a provider section name matches an existing `helpGroup` from statically defined subcommands, the entries are appended to that group rather than creating a duplicate heading.
+
+### Key Points
+
+1. **Zero startup cost** -- The provider class is stored as a reference and only instantiated when help is rendered
+2. **Works with both `@CommandDefinition` and `@GroupCommandDefinition`**
+3. **HelpEntry** is a simple value class with `name()` and `description()` (description is optional)
+4. **Return an empty map** (not null) if there are no additional sections to show

content/docs/aesh/group-commands.md

@@ -38,6 +38,8 @@ 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 |
+| `helpGroup` | `String` | `""` | Group heading when listed as a subcommand in parent's help |
+| `helpSectionProvider` | `Class<? extends HelpSectionProvider>` | `NullHelpSectionProvider.class` | Provider for dynamic help sections |
 
 ## Subcommands
 

content/docs/aesh/option-groups.md

@@ -23,6 +23,7 @@ The `@OptionGroup` annotation defines key=value pair options collected into a `M
 | `activator` | `Class<? extends OptionActivator>` | `NullActivator.class` | Custom activator |
 | `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)) |
 
 ## Basic Example
 

content/docs/aesh/option-lists.md

@@ -26,6 +26,8 @@ The `@OptionList` annotation defines options that accept multiple values separat
 | `parser` | `Class<? extends OptionParser>` | `AeshOptionParser.class` | Custom parser |
 | `aliases` | `String[]` | `{}` | Alternative long names for this option |
 | `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)) |
 
 ## Basic Example
 

content/docs/aesh/options.md

@@ -33,6 +33,8 @@ The `@Option` annotation defines command-line options (flags with values).
 | `parser` | `Class<? extends OptionParser>` | `AeshOptionParser.class` | Custom parser |
 | `aliases` | `String[]` | `{}` | Alternative long names for this option |
 | `helpGroup` | `String` | `""` | Group heading for this option in help output |
+| `exclusiveWith` | `String[]` | `{}` | Names of mutually exclusive options (without `--` prefix) |
+| `visibility` | `OptionVisibility` | `BRIEF` | Controls help and completion visibility (`BRIEF`, `FULL`, `HIDDEN`) |
 | `descriptionUrl` | `String` | `""` | URL for option documentation (clickable in supported terminals) |
 | `url` | `boolean` | `false` | Treat option value as a URL (rendered as clickable link) |
 
@@ -540,6 +542,204 @@ ProcessedOptionBuilder.builder()
         .build();
 ```
 
+## 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.
+
+### Basic Usage
+
+```java
+@CommandDefinition(name = "export", description = "Export data", generateHelp = true)
+public class ExportCommand implements Command<CommandInvocation> {
+
+    @Option(hasValue = false, description = "Output as JSON", exclusiveWith = {"xml", "csv"})
+    private boolean json;
+
+    @Option(hasValue = false, description = "Output as XML", exclusiveWith = {"json", "csv"})
+    private boolean xml;
+
+    @Option(hasValue = false, description = "Output as CSV", exclusiveWith = {"json", "xml"})
+    private boolean csv;
+
+    @Option(hasValue = false, description = "Verbose output")
+    private boolean verbose;
+
+    @Override
+    public CommandResult execute(CommandInvocation invocation) {
+        return CommandResult.SUCCESS;
+    }
+}
+```
+
+Usage:
+```bash
+# Valid -- only one format selected
+$ export --json
+$ export --xml --verbose
+
+# Invalid -- mutually exclusive options used together
+$ export --json --xml
+Error: Options --json and --xml are mutually exclusive.
+```
+
+### How It Works
+
+1. Each option lists the names of options it conflicts with (long names, without the `--` prefix)
+2. The relationship should be declared on both sides: if `--json` lists `xml`, then `--xml` should list `json`
+3. Validation runs after parsing, at the same point as required option checks
+4. Non-exclusive options (like `--verbose` above) can be freely combined with any exclusive option
+
+### Tab Completion
+
+When an exclusive option has been set, conflicting options are automatically filtered from tab completion. For example, after typing `export --json`, pressing Tab will not suggest `--xml` or `--csv`.
+
+### With OptionList
+
+`exclusiveWith` also works with `@OptionList`:
+
+```java
+@OptionList(description = "Items to process", exclusiveWith = {"file"})
+private List<String> items;
+
+@Option(description = "Read items from file", exclusiveWith = {"items"})
+private String file;
+```
+
+### Programmatic API
+
+When building commands programmatically, use `ProcessedOptionBuilder`:
+
+```java
+ProcessedOptionBuilder.builder()
+        .name("json")
+        .type(boolean.class)
+        .hasValue(false)
+        .exclusiveWith("xml", "csv")
+        .build();
+```
+
+## Visibility Levels
+
+The `visibility` property controls whether an option appears in `--help` output and tab completion. This is useful for organizing help output by importance — showing essential options by default and revealing advanced or deprecated options only on request.
+
+### Visibility Values
+
+| Level | `--help` | `--help=all` | Tab completion |
+|-------|----------|--------------|----------------|
+| `BRIEF` (default) | Shown | Shown | Shown |
+| `FULL` | Hidden | Shown | Shown |
+| `HIDDEN` | Hidden | Hidden | Hidden |
+
+### Basic Usage
+
+```java
+@CommandDefinition(name = "serve", description = "Start server", generateHelp = true)
+public class ServeCommand implements Command<CommandInvocation> {
+
+    @Option(shortName = 'p', description = "Server port")
+    private int port;
+
+    @Option(description = "Bind address")
+    private String host;
+
+    @Option(description = "Enable request tracing", visibility = OptionVisibility.FULL)
+    private boolean trace;
+
+    @Option(description = "Thread pool size", visibility = OptionVisibility.FULL)
+    private int threads;
+
+    @Option(description = "Internal diagnostic token", visibility = OptionVisibility.HIDDEN)
+    private String diagnosticToken;
+
+    @Override
+    public CommandResult execute(CommandInvocation invocation) {
+        return CommandResult.SUCCESS;
+    }
+}
+```
+
+Default help shows only essential options:
+
+```bash
+$ serve --help
+Usage: serve [<options>]
+Start server
+
+Options:
+  -p, --port      Server port
+  --host          Bind address
+  -h, --help      Display help (use --help=all for all options)
+```
+
+Full help reveals advanced options:
+
+```bash
+$ serve --help=all
+Usage: serve [<options>]
+Start server
+
+Options:
+  -p, --port      Server port
+  --host          Bind address
+  --trace         Enable request tracing
+  --threads       Thread pool size
+  -h, --help      Display help (use --help=all for all options)
+```
+
+The `--diagnosticToken` option never appears in help but still works when typed explicitly.
+
+### When to Use Each Level
+
+- **`BRIEF`** — Options every user needs to know about. This is the default; existing commands are unaffected.
+- **`FULL`** — Advanced tuning, debugging, or rarely-used options. Power users can discover them with `--help=all`.
+- **`HIDDEN`** — Internal, deprecated, or experimental options that should not be discoverable. They still parse and work when used explicitly.
+
+### Tab Completion
+
+`HIDDEN` options are excluded from tab completion. `BRIEF` and `FULL` options are both offered during completion — visibility only affects help output for `FULL` options.
+
+### With Help Grouping
+
+Visibility works with `helpGroup`. A group heading is only printed if it contains at least one visible option:
+
+```java
+@Option(description = "Enable tracing", helpGroup = "Diagnostics",
+        visibility = OptionVisibility.FULL)
+private boolean trace;
+
+@Option(description = "Profile mode", helpGroup = "Diagnostics",
+        visibility = OptionVisibility.FULL)
+private boolean profile;
+```
+
+With `--help`, the "Diagnostics" group is omitted entirely. With `--help=all`, it appears with both options.
+
+### With OptionList and OptionGroup
+
+Visibility also works with `@OptionList` and `@OptionGroup`:
+
+```java
+@OptionList(description = "Debug modules", visibility = OptionVisibility.FULL)
+private List<String> debugModules;
+
+@OptionGroup(shortName = 'X', description = "Internal flags",
+             visibility = OptionVisibility.HIDDEN)
+private Map<String, String> internalFlags;
+```
+
+### Programmatic API
+
+When building commands programmatically, use `ProcessedOptionBuilder`:
+
+```java
+ProcessedOptionBuilder.builder()
+        .name("trace")
+        .type(boolean.class)
+        .description("Enable request tracing")
+        .visibility(OptionVisibility.FULL)
+        .build();
+```
+
 ## Required Options
 
 ```java