added dynamic default value provider docs

Author: stalep

content/docs/aesh/annotation-processor.md

@@ -192,4 +192,4 @@ public class DeployCommand extends BaseCommand {
 - **Java 8+** -- The processor targets source version 8
 - **No code changes required** -- Drop in the dependency and the processor runs automatically
 - **Fully backward compatible** -- Removing the dependency reverts to the reflection path with no behavior change
-- **Works with all Aesh features** -- Custom validators, completers, converters, activators, renderers, result handlers, and option parsers are all supported
+- **Works with all Aesh features** -- Custom validators, completers, converters, activators, renderers, result handlers, option parsers, default value providers, optional-value options, negatable options, stop-at-positional, and inherited options are all supported

content/docs/aesh/command-definition.md

@@ -25,6 +25,7 @@ The `@CommandDefinition` annotation is used to define a command class.
 | `validator` | `Class<? extends CommandValidator>` | `NullCommandValidator.class` | Validator to run before execution |
 | `resultHandler` | `Class<? extends ResultHandler>` | `NullResultHandler.class` | Handler to run after execution |
 | `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 |
 | `helpUrl` | `String` | `""` | URL to documentation (shown in `--help` output) |
 
@@ -68,6 +69,71 @@ Return one of the following:
 - `CommandResult.FAILURE` - Command failed
 - `CommandResult.RETURN` - Return from current subcommand
 
+## Dynamic Default Value Provider
+
+The `defaultValueProvider` attribute specifies a class that resolves option defaults at runtime. This is useful when defaults come from configuration files, environment variables, or other external sources not known at compile time.
+
+### Implementing a Provider
+
+Create a class that implements `DefaultValueProvider`:
+
+```java
+public class ConfigDefaultProvider implements DefaultValueProvider {
+
+    @Override
+    public String defaultValue(ProcessedOption option) {
+        // Use option.name() and option.parent().name() to build a config key
+        String key = option.parent().name() + "." + option.name();
+        return Configuration.get(key);  // returns null if not configured
+    }
+}
+```
+
+### Registering the Provider
+
+```java
+@CommandDefinition(
+    name = "init",
+    description = "Initialize a project",
+    defaultValueProvider = ConfigDefaultProvider.class
+)
+public class InitCommand implements Command<CommandInvocation> {
+
+    @Option(defaultValue = "hello")
+    private String template;
+
+    @Option
+    private String editor;
+
+    @Override
+    public CommandResult execute(CommandInvocation invocation) {
+        invocation.println("Template: " + template);
+        invocation.println("Editor: " + editor);
+        return CommandResult.SUCCESS;
+    }
+}
+```
+
+### Value Precedence
+
+When determining option values, the precedence is (highest to lowest):
+
+1. **User-provided value** -- Explicitly set on the command line
+2. **Dynamic default** -- Returned by the `DefaultValueProvider` (if non-null)
+3. **Static default** -- The `defaultValue` from the annotation
+4. **null** -- If nothing else is set
+
+If the provider returns `null` for an option, aesh falls back to the static `defaultValue`. This lets you use annotation defaults as fallbacks:
+
+```java
+// Provider returns "from-config" for template -> uses "from-config"
+// Provider returns null for editor -> falls back to static default "vi"
+@Option(defaultValue = "vi")
+private String editor;
+```
+
+See [Options - Dynamic Default Values](/docs/aesh/options#dynamic-default-values) for more details.
+
 ## Stop at First Positional
 
 When `stopAtFirstPositional = true`, option parsing stops as soon as the first positional argument is consumed. All remaining tokens are treated as positional arguments, even if they look like options.

content/docs/aesh/options.md

@@ -471,15 +471,54 @@ $ connect -h dev-db.local -p 5434
 Connecting to john@dev-db.local:5434/myapp
 ```
 
+### Dynamic Default Values
+
+For defaults that must be resolved at runtime (e.g., from configuration files, databases, or user profiles), use a `DefaultValueProvider`. The provider is registered on the command, not on individual options:
+
+```java
+public class AppConfigProvider implements DefaultValueProvider {
+
+    @Override
+    public String defaultValue(ProcessedOption option) {
+        // Build a hierarchical key from command + option name
+        String key = option.parent().name() + "." + option.name();
+        return AppConfig.instance().get(key);  // null if not configured
+    }
+}
+
+@CommandDefinition(
+    name = "run",
+    description = "Run application",
+    defaultValueProvider = AppConfigProvider.class
+)
+public class RunCommand implements Command<CommandInvocation> {
+
+    @Option(description = "Debug port", defaultValue = "4004")
+    private String debug;
+
+    @Option(description = "JFR settings")
+    private String jfr;
+
+    @Override
+    public CommandResult execute(CommandInvocation invocation) {
+        // debug = config value if set, else "4004", unless user provided a value
+        return CommandResult.SUCCESS;
+    }
+}
+```
+
+If the provider returns `null` for an option, the static `defaultValue` from the annotation is used as a fallback. See [Command Definition - Dynamic Default Value Provider](/docs/aesh/command-definition#dynamic-default-value-provider) for more details.
+
 ### Priority Order
 
 When determining option values, Æsh uses this priority (highest to lowest):
 
 1. **Command-line argument** - Explicitly provided by user
-2. **Environment variable / System property** - If referenced in `defaultValue`
-3. **Fallback value** - Value after `:` in the `defaultValue` expression
-4. **Field initializer** - Java field initialization value
-5. **null** - If nothing else is set
+2. **Dynamic default** - From `DefaultValueProvider` (if non-null)
+3. **Static default / Environment variable / System property** - From `defaultValue` annotation
+4. **Fallback value** - Value after `:` in the `defaultValue` expression
+5. **Field initializer** - Java field initialization value
+6. **null** - If nothing else is set
 
 ### Multiple Default Values