feat: Add module docs, Enum coercion, tracebacks, and toggle improvements

- Add comprehensive module docstrings across the codebase for better clarity and documentation.
- Refactor Enum classes (e.g., FileType, ConfirmType) to use `_missing_` for built-in coercion from strings.
- Add `encoding` attribute to `LoadFileAction`, `SaveFileAction`, and `SelectFileAction` for more flexible file handling.
- Enable lazy file loading by default in `SelectFileAction` to improve performance.
- Simplify bottom bar toggle behavior: all toggles now use `ctrl+<key>`, eliminating the need for key conflict checks with Falyx commands.
- Add `ignore_in_history` attribute to `Command` to refine how `ExecutionRegistry` identifies the last valid result.
- Improve History command output: now includes tracebacks when displaying exceptions.

falyx/completer.py

@@ -1,3 +1,20 @@
+# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""
+Provides `FalyxCompleter`, an intelligent autocompletion engine for Falyx CLI
+menus using Prompt Toolkit.
+
+This completer supports:
+- Command key and alias completion (e.g. `R`, `HELP`, `X`)
+- Argument flag completion for registered commands (e.g. `--tag`, `--name`)
+- Context-aware suggestions based on cursor position and argument structure
+- Interactive value completions (e.g. choices and suggestions defined per argument)
+
+Completions are sourced from `CommandArgumentParser.suggest_next`, which analyzes
+parsed tokens to determine appropriate next arguments, flags, or values.
+
+Integrated with the `Falyx.prompt_session` to enhance the interactive experience.
+"""
+
 from __future__ import annotations
 
 import shlex
@@ -11,12 +28,38 @@ if TYPE_CHECKING:
 
 
 class FalyxCompleter(Completer):
-    """Completer for Falyx commands."""
+    """
+    Prompt Toolkit completer for Falyx CLI command input.
+
+    This completer provides real-time, context-aware suggestions for:
+    - Command keys and aliases (resolved via Falyx._name_map)
+    - CLI argument flags and values for each command
+    - Suggestions and choices defined in the associated CommandArgumentParser
+
+    It leverages `CommandArgumentParser.suggest_next()` to compute valid completions
+    based on current argument state, including:
+        - Remaining required or optional flags
+        - Flag value suggestions (choices or custom completions)
+        - Next positional argument hints
+
+    Args:
+        falyx (Falyx): The Falyx menu instance containing all command mappings and parsers.
+    """
 
     def __init__(self, falyx: "Falyx"):
         self.falyx = falyx
 
     def get_completions(self, document: Document, complete_event) -> Iterable[Completion]:
+        """
+        Yield completions based on the current document input.
+
+        Args:
+            document (Document): The prompt_toolkit document containing the input buffer.
+            complete_event: The completion trigger event (unused).
+
+        Yields:
+            Completion objects matching command keys or argument suggestions.
+        """
         text = document.text_before_cursor
         try:
             tokens = shlex.split(text)
@@ -40,6 +83,8 @@ class FalyxCompleter(Completer):
         stub = "" if cursor_at_end_of_token else tokens[-1]
 
         try:
+            if not command.arg_parser:
+                return
             suggestions = command.arg_parser.suggest_next(
                 parsed_args + ([stub] if stub else [])
             )
@@ -50,6 +95,15 @@ class FalyxCompleter(Completer):
             return
 
     def _suggest_commands(self, prefix: str) -> Iterable[Completion]:
+        """
+        Suggest top-level command keys and aliases based on the given prefix.
+
+        Args:
+            prefix (str): The user input to match against available commands.
+
+        Yields:
+            Completion: Matching keys or aliases from all registered commands.
+        """
         prefix = prefix.upper()
         keys = [self.falyx.exit_command.key]
         keys.extend(self.falyx.exit_command.aliases)