Added documentation to describe suggestions and ghost text support

Author: stalep

content/docs/aesh/_index.md

@@ -65,6 +65,7 @@ That's it! Æsh automatically:
 ### User Experience
 - **Tab completion** - Built-in completers for files, booleans, and enums
 - **Custom completers** - Add domain-specific completions
+- **[Ghost text suggestions](ghost-text-suggestions)** - Inline suggestions for commands, subcommands, and options as you type
 - **Auto-generated help** - `--help` automatically generated from your metadata
 - **Input validation** - Built-in and custom validators for options and arguments
 - **Error messages** - Clear, helpful error messages for users
@@ -73,6 +74,7 @@ That's it! Æsh automatically:
 - **Validators** - Ensure option values meet your requirements
 - **Converters** - Convert string input to custom types
 - **Completers** - Provide tab completion suggestions
+- **Suggestion providers** - Inline ghost text suggestions
 - **Activators** - Conditionally enable/disable options
 - **Renderers** - Customize help output format
 - **Custom parsers** - Override default parsing behavior

content/docs/aesh/completers.md

@@ -7,6 +7,10 @@ weight: 8
 
 Completers provide tab-completion suggestions for options and arguments.
 
+{{< callout type="info" >}}
+Looking for inline ghost text suggestions instead of tab completion? See [Ghost Text Suggestions](../ghost-text-suggestions) for automatic command, subcommand, and option suggestions as you type.
+{{< /callout >}}
+
 ## OptionCompleter Interface
 
 ```java

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

@@ -0,0 +1,125 @@
+---
+date: '2026-02-26T10:00:00+01:00'
+draft: false
+title: 'Ghost Text Suggestions'
+weight: 9
+---
+
+Ghost text suggestions display inline, dimmed text ahead of the cursor as you type, showing what Æsh predicts you want to enter. Unlike [tab completion](completers), which requires pressing Tab, ghost text appears automatically and can be accepted by pressing the right arrow key.
+
+## How It Works
+
+As you type, ghost text suggestions appear automatically:
+
+```
+myapp> ca|che                    ← "che" appears dimmed after cursor
+myapp> connect --ho|st=          ← "st=" appears dimmed after cursor
+myapp> git co|mmit               ← "mmit" appears dimmed after cursor
+```
+
+- **Right arrow** accepts the suggestion
+- **Keep typing** to narrow or dismiss the suggestion
+- Only shown when there is exactly one unambiguous match
+
+## CommandSuggestionProvider
+
+`CommandSuggestionProvider` uses the command registry to suggest command names, subcommand names, and option names as you type. It implements the `SuggestionProvider` interface from Æsh Readline.
+
+### What It Suggests
+
+| Context | Example Input | Suggestion |
+|---------|--------------|------------|
+| Command names | `ca` | `che` (from `cache`) |
+| Subcommand names | `git co` | `mmit` (from `commit`) |
+| Option names | `connect --ho` | `st=` (from `--host`) |
+
+Suggestions are only shown when there is a single unambiguous match. If the input `c` could match both `cache` and `connect`, no suggestion is shown.
+
+For options that accept a value, the suggestion appends `=` after the option name. Boolean options (flags) do not get the trailing `=`.
+
+### Setup
+
+Create a `CommandSuggestionProvider` from your command registry and attach it to the console:
+
+```java
+import org.aesh.command.impl.completer.CommandSuggestionProvider;
+import org.aesh.console.ReadlineConsole;
+
+ReadlineConsole console = new ReadlineConsole(settings);
+
+// Create suggestion provider from the console's registry
+CommandSuggestionProvider<?> provider =
+        new CommandSuggestionProvider<>(console.getCommandRegistry());
+
+console.setSuggestionProvider(provider);
+console.start();
+```
+
+### With AeshConsoleRunner
+
+If you use `AeshConsoleRunner`, you can access the underlying `ReadlineConsole` to set up suggestions:
+
+```java
+ReadlineConsole console = new ReadlineConsole(settings);
+console.setPrompt(new Prompt("myapp> "));
+console.setSuggestionProvider(
+        new CommandSuggestionProvider<>(console.getCommandRegistry()));
+console.start();
+```
+
+## CompositeSuggestionProvider
+
+You can combine multiple suggestion sources using `CompositeSuggestionProvider`. The first provider that returns a non-null suggestion wins. This lets you layer history-based suggestions with command-based suggestions:
+
+```java
+import org.aesh.readline.CompositeSuggestionProvider;
+import org.aesh.readline.SuggestionProvider;
+
+// History-based suggestions (checked first)
+SuggestionProvider historyProvider = buffer -> {
+    // Return matching history entry suffix, or null
+    return findHistoryMatch(buffer);
+};
+
+// Command registry suggestions (fallback)
+CommandSuggestionProvider<?> commandProvider =
+        new CommandSuggestionProvider<>(console.getCommandRegistry());
+
+// Combine: history takes priority, falls back to commands
+CompositeSuggestionProvider composite =
+        new CompositeSuggestionProvider(historyProvider, commandProvider);
+
+console.setSuggestionProvider(composite);
+```
+
+## Custom SuggestionProvider
+
+You can implement the `SuggestionProvider` interface directly for custom suggestion logic:
+
+```java
+import org.aesh.readline.SuggestionProvider;
+
+SuggestionProvider myProvider = buffer -> {
+    // Return the suffix to append as ghost text, or null for no suggestion
+    if (buffer.startsWith("hel")) {
+        return "lo";
+    }
+    return null;
+};
+
+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.
+
+## Ghost Text vs Tab Completion
+
+| Feature | Ghost Text | Tab Completion |
+|---------|-----------|----------------|
+| **Trigger** | Automatic as you type | Press Tab |
+| **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 |
+
+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/readline/_index.md

@@ -34,6 +34,7 @@ Think of it this way: Æsh is built **on top of** Æsh Readline. Æsh provides t
 - **Line Editing** - Undo/redo support with customizable key bindings
 - **History Management** - Search, persistence, and navigation
 - **Tab Completion** - Extensible completion system
+- **Ghost Text Suggestions** - Inline suggestion display via `SuggestionProvider`
 - **Input Masking** - Password and sensitive input handling
 - **Paste Buffer** - Copy/paste operations
 - **Edit Modes** - Both Emacs and Vi editing modes

content/docs/readline/completion.md

@@ -5,7 +5,7 @@ title: 'Completion'
 weight: 6
 ---
 
-Æsh Readline supports tab completion for commands and options.
+Æsh Readline supports tab completion for commands and options, as well as inline ghost text suggestions via `SuggestionProvider`.
 
 ## Completion Class
 
@@ -181,3 +181,47 @@ Completion colored = new Completion(
     TerminalColor.RED
 );
 ```
+
+## Ghost Text Suggestions
+
+In addition to tab completion, Æsh Readline supports inline ghost text suggestions that appear automatically as the user types. Ghost text is rendered as dimmed text after the cursor and can be accepted with the right arrow key.
+
+### SuggestionProvider Interface
+
+```java
+import org.aesh.readline.SuggestionProvider;
+
+SuggestionProvider provider = buffer -> {
+    // Return the suffix to display as ghost text, or null for no suggestion
+    if (buffer.startsWith("hel")) {
+        return "lo";
+    }
+    return null;
+};
+```
+
+### Setting Up Suggestions
+
+```java
+Readline readline = ReadlineBuilder.builder().build();
+readline.setSuggestionProvider(provider);
+```
+
+### CompositeSuggestionProvider
+
+Chain multiple providers together. The first provider that returns a non-null result wins:
+
+```java
+import org.aesh.readline.CompositeSuggestionProvider;
+
+CompositeSuggestionProvider composite = new CompositeSuggestionProvider(
+    historyProvider,   // checked first
+    commandProvider    // fallback
+);
+
+readline.setSuggestionProvider(composite);
+```
+
+{{< callout type="info" >}}
+If you're using the Æsh command framework, see [Ghost Text Suggestions](/docs/aesh/ghost-text-suggestions) for the built-in `CommandSuggestionProvider` that automatically suggests command names, subcommands, and options from your command registry.
+{{< /callout >}}