Update docs for tail tip suggestions, custom parser fallback, unified synopsis

- ghost-text-suggestions.md: Add TailTipSuggestionProvider section with
  setup, priority ordering, and combining with CommandSuggestionProvider
- settings.md: Add tailTipSuggestions option with description and table entry
- options.md: Document custom parser + fallback chain behavior (#511),
  update fallbackValue description to mention custom parser support
- documentation-generation.md: Update SYNOPSIS description to mention
  unified formatting across all doc formats

Author: stalep

content/docs/aesh/documentation-generation.md

@@ -80,7 +80,7 @@ Each generated page includes:
 | Section | Content |
 |---------|---------|
 | **NAME** | Command name and description |
-| **SYNOPSIS** | Formatted usage with options, arguments, and `[COMMAND]` placeholder for groups |
+| **SYNOPSIS** | Formatted usage with short flag clusters, negatable options, exclusive pipes, value placeholders, and `[COMMAND]` placeholder for groups. Consistent across all formats and `--help`. |
 | **DESCRIPTION** | Command description from the annotation |
 | **OPTIONS** | All visible options with short/long names, value placeholders, defaults, aliases, and negatable display |
 | **ARGUMENTS** | Positional parameters with labels |

content/docs/aesh/ghost-text-suggestions.md

@@ -146,6 +146,77 @@ console.setSuggestionProvider(myProvider);
 
 The `suggest` method receives the current input buffer and returns the text to display after the cursor as ghost text. Return `null` when there is no suggestion.
 
+## TailTipSuggestionProvider
+
+`TailTipSuggestionProvider` displays parameter hints after the cursor, showing remaining options and arguments that haven't been provided yet. Unlike `CommandSuggestionProvider` which completes the current word, tail tips show the full synopsis of what comes next.
+
+```
+myapp> deploy --force |[-e=<environment>] <app>
+                       ^^^^^^^^^^^^^^^^^^^^^^^^^ remaining params (dimmed)
+```
+
+As the user fills in parameters, the tail tip updates to show only what's still needed:
+
+```
+myapp> deploy --force -e prod |<app>
+                               ^^^^^ only argument left (dimmed)
+```
+
+### How it works
+
+- Only activates when the buffer ends with a space (the user has finished typing a word)
+- Parses the current buffer to determine which options have already been provided
+- Builds a synopsis of remaining options and arguments
+- Uses the same formatting as `--help` synopsis (short flag clusters, exclusive pipes, value placeholders)
+- Caches the last result to avoid re-parsing on unchanged input
+
+### Setup
+
+Tail tips are opt-in via Settings and only apply to interactive `ReadlineConsole` mode (not `AeshRuntimeRunner`):
+
+```java
+Settings settings = SettingsBuilder.builder()
+        .tailTipSuggestions(true)   // default: false
+        .commandRegistry(registry)
+        .build();
+
+ReadlineConsole console = new ReadlineConsole(settings);
+console.start();
+```
+
+When enabled, the tail tip provider is automatically added as the lowest-priority provider in the suggestion chain. History suggestions and command auto-suggest take priority when they have a match.
+
+### Priority ordering
+
+When `tailTipSuggestions` is enabled and `setSuggestionProvider()` is also used, the chain is:
+
+1. History suggestions (if history is available)
+2. Your suggestion provider (e.g., `CommandSuggestionProvider`)
+3. Tail tip suggestions (only when others return null)
+
+This means mid-word typing gets auto-suggest, and after completing a word (trailing space), the tail tip shows remaining parameters.
+
+### Combining with CommandSuggestionProvider
+
+For the best experience, use both providers together:
+
+```java
+Settings settings = SettingsBuilder.builder()
+        .tailTipSuggestions(true)
+        .commandRegistry(registry)
+        .build();
+
+ReadlineConsole console = new ReadlineConsole(settings);
+console.setSuggestionProvider(
+        new CommandSuggestionProvider<>(console.getCommandRegistry()));
+console.start();
+```
+
+This gives:
+- History auto-suggest when a history entry matches
+- Command/option name completion while typing
+- Parameter hints after each completed word
+
 ## Ghost Text vs Tab Completion
 
 | Feature | Ghost Text | Tab Completion |
@@ -154,6 +225,6 @@ The `suggest` method receives the current input buffer and returns the text to d
 | **Display** | Inline dimmed text | List below prompt |
 | **Matches** | Single unambiguous only | Shows all matches |
 | **Accept** | Right arrow | Tab / Enter |
-| **Scope** | Commands, subcommands, options | Options, arguments, custom values |
+| **Scope** | Commands, subcommands, options, tail tips | Options, arguments, custom values |
 
 Both features complement each other. Ghost text gives fast inline suggestions for unambiguous matches, while tab completion helps explore all available options when there are multiple possibilities.

content/docs/aesh/options.md

@@ -220,7 +220,7 @@ When `fallbackValue` is set:
 3. **Explicit value (`--debug=5005`)** uses the given value, same as any normal option
 4. **Not specified** leaves the field as `null` (or the `defaultValue` / `DefaultValueProvider` value if configured)
 
-This eliminates the need for custom `OptionParser` implementations to handle the three-state pattern.
+This works with both the built-in `AeshOptionParser` and custom `OptionParser` implementations -- the fallback chain runs automatically after any parser returns without setting a value.
 
 ### Compared to `optionalValue`
 
@@ -1089,6 +1089,64 @@ The `fallbackValue()` method is a `default` method returning `null`. Existing `D
 | Bare flag needs a value from config/env | `DefaultValueProvider.fallbackValue()` |
 | All of the above combined | Both annotation + provider, resolution chain handles priority |
 
+### Custom Parsers and the Fallback Chain
+
+When using a custom `OptionParser` (via `@Option(parser = MyParser.class)`), the value resolution chain applies automatically. If the custom parser decides not to consume a token and returns without calling `addValue()`, the framework applies the fallback chain (provider `fallbackValue()` -> annotation `fallbackValue` -> annotation `defaultValue`).
+
+This separates the **parsing concern** (which tokens to consume) from the **value resolution concern** (what value to use when no tokens were consumed):
+
+```java
+public class DebugOptionParser implements OptionParser {
+    private static final Pattern PORT = Pattern.compile("\\d+");
+
+    @Override
+    public void parse(ParsedLineIterator iter, ProcessedOption option)
+            throws OptionParserException {
+        // Consume the option name token
+        iter.pollParsedWord();
+
+        // Peek at next token -- only consume if it matches a port number
+        if (iter.hasNextWord()) {
+            String next = iter.peekWord();
+            if (!next.startsWith("-") && PORT.matcher(next).matches()) {
+                option.addValue(next);
+                iter.pollParsedWord();
+                return;
+            }
+        }
+        // No addValue() call -- framework applies the fallback chain
+    }
+}
+
+@CommandDefinition(name = "run", description = "Run script")
+public class RunCommand implements Command<CommandInvocation> {
+
+    @Option(name = "debug", parser = DebugOptionParser.class,
+            fallbackValue = "4004")
+    String debug;
+
+    @Argument
+    String script;
+}
+```
+
+```bash
+$ run --debug=5005 test.java   # debug = "5005" (parser consumed)
+$ run --debug 5005 test.java   # debug = "5005" (parser consumed)
+$ run --debug test.java        # debug = "4004" (parser skipped, fallback applied)
+$ run --debug                  # debug = "4004" (parser skipped, fallback applied)
+```
+
+The custom parser contract:
+
+| Parser action | Result |
+|---|---|
+| `option.addValue(x)` | Value is `x` -- no fallback applied |
+| `option.addValue("")` | Value is `""` -- no fallback applied (explicit empty) |
+| No `addValue()` call | Fallback chain runs (provider -> annotation -> default) |
+
+This eliminates the need for custom parsers to set sentinel values (like `""`) and handle fallback resolution manually.
+
 ### Multiple Default Values
 
 For options that accept multiple values (lists/arrays), provide multiple defaults:

content/docs/aesh/settings.md

@@ -346,6 +346,20 @@ SettingsBuilder.builder()
 
 See [Sub-Command Mode](/docs/aesh/sub-command-mode) for complete documentation.
 
+### Ghost Text and Tail Tips
+
+#### tailTipSuggestions(boolean)
+
+Enables tail tip suggestions -- dimmed parameter hints shown after the cursor in interactive mode. When enabled, remaining options and arguments are displayed as ghost text after each completed word. Only applies to `ReadlineConsole` (REPL mode), not `AeshRuntimeRunner`. Default: `false`
+
+```java
+SettingsBuilder.builder()
+        .tailTipSuggestions(true)
+        .build();
+```
+
+See [Ghost Text Suggestions](../ghost-text-suggestions#tailtipsuggestionprovider) for details on how tail tips work and how they interact with other suggestion providers.
+
 ### Additional Options
 
 #### readInputrc(boolean)
@@ -466,6 +480,7 @@ public CommandResult execute(CommandInvocation invocation) {
 | `setRedirection` | `boolean` | `true` | Enable redirection operators |
 | `readInputrc` | `boolean` | `true` | Read .inputrc configuration |
 | `echoCtrl` | `boolean` | `true` | Echo control characters |
+| `tailTipSuggestions` | `boolean` | `false` | Show parameter hints after cursor |
 | `subCommandModeSettings` | `SubCommandModeSettings` | defaults | Sub-command mode configuration |
 
 ## Best Practices