feat(core): advance options/state handling and workflow execution integration

- extend OptionsManager to support multi-namespace option resolution and toggling
- integrate OptionsManager more deeply across Action, ChainedAction, and ActionGroup
- propagate shared runtime configuration through execution layers
- refine action composition model (sequential + parallel execution semantics)
- improve lifecycle consistency across BaseAction, Action, ChainedAction, and ActionGroup
- begin aligning execution flow with centralized context and options handling

wip: routing and root option parsing behavior still in progress

.gitignore

@@ -15,3 +15,4 @@ build/
 .vscode/
 coverage.xml
 .coverage
+.config.json

README.md

@@ -10,7 +10,7 @@
 - ⚙️ Full lifecycle hooks (before, after, success, error, teardown)
 - 📊 Execution tracing, logging, and introspection
 - 🧙‍♂️ Async-first design with Process support
-- 🧩 Extensible CLI menus and customizable output
+- 🧩 Extensible CLI menus, customizable bottom bars, and keyboard shortcuts
 
 > Built for developers who value *clarity*, *resilience*, and *visibility* in their terminal workflows.
 
@@ -21,12 +21,13 @@
 Modern CLI tools deserve the same resilience as production systems. Falyx makes it easy to:
 
 - Compose workflows using `Action`, `ChainedAction`, or `ActionGroup`
-- Inject the result of one step into the next (`last_result`)
+- Inject the result of one step into the next (`last_result` / `auto_inject`)
-- Handle flaky operations with retries and exponential backoff
+- Handle flaky operations with retries, backoff, and jitter
 - Roll back safely on failure with structured undo logic
-- Add observability with execution timing, result tracking, and hooks
+- Add observability with timing, tracebacks, and lifecycle hooks
 - Run in both interactive *and* headless (scriptable) modes
-- Customize output with Rich `Table`s (grouping, theming, etc.)
+- Support config-driven workflows with YAML or TOML
+- Visualize tagged command groups and menu state via Rich tables
 
 ---
 
@@ -60,6 +61,7 @@ async def flaky_step():
     await asyncio.sleep(0.2)
     if random.random() < 0.5:
         raise RuntimeError("Random failure!")
+    print("ok")
     return "ok"
 
 # Create the actions
@@ -78,6 +80,8 @@ falyx.add_command(
     preview_before_confirm=True,
     confirm=True,
     retry_all=True,
+    spinner=True,
+    style="cyan",
 )
 
 # Entry point
@@ -86,76 +90,131 @@ if __name__ == "__main__":
 ```
 
 ```bash
-❯ python simple.py
+$ python simple.py
                           🚀 Falyx Demo
 
            [R] Run My Pipeline
-  [Y] History                                         [Q] Exit
+           [H] Help              [Y] History   [X] Exit
 
 >
 ```
 
 ```bash
-❯ python simple.py run R
+$ python simple.py run r
 Command: 'R' — Run My Pipeline
 └── ⛓ ChainedAction 'my_pipeline'
     ├── ⚙ Action 'step_1'
     │   ↻ Retries: 3x, delay 1.0s, backoff 2.0x
     └── ⚙ Action 'step_2'
         ↻ Retries: 3x, delay 1.0s, backoff 2.0x
-Confirm execution of R — Run My Pipeline (calls `my_pipeline`)  [Y/n] y
+❓ Confirm execution of R — Run My Pipeline (calls `my_pipeline`)  [Y/n] > y
-[2025-04-15 22:03:57] WARNING   ⚠️ Retry attempt 1/3 failed due to 'Random failure!'.
+[2025-07-20 09:29:35] WARNING   Retry attempt 1/3 failed due to 'Random failure!'.
-✅ Result: ['ok', 'ok']
+ok
+[2025-07-20 09:29:38] WARNING   Retry attempt 1/3 failed due to 'Random failure!'.
+ok
 ```
 
 ---
 
 ## 📦 Core Features
 
-- ✅ Async-native `Action`, `ChainedAction`, `ActionGroup`
+- ✅ Async-native `Action`, `ChainedAction`, `ActionGroup`, `ProcessAction`
-- 🔁 Retry policies + exponential backoff
+- 🔁 Retry policies with delay, backoff, jitter — opt-in per action or globally
-- ⛓ Rollbacks on chained failures
+- ⛓ Rollbacks and lifecycle hooks for chained execution
-- 🎛️ Headless or interactive CLI with argparse and prompt_toolkit
+- 🎛️ Headless or interactive CLI powered by `argparse` + `prompt_toolkit`
-- 📊 Built-in execution registry, result tracking, and timing
+- 📊 In-memory `ExecutionRegistry` with result tracking, timing, and tracebacks
-- 🧠 Supports `ProcessAction` for CPU-bound workloads
+- 🌐 CLI menu construction via config files or Python
-- 🧩 Custom `Table` rendering for CLI menu views
+- ⚡ Bottom bar toggle switches and counters with `Ctrl+<key>` shortcuts
-- 🔍 Hook lifecycle: `before`, `on_success`, `on_error`, `after`, `on_teardown`
+- 🔍 Structured confirmation prompts and help rendering
+- 🪵 Flexible logging: Rich console for devs, JSON logs for ops
 
 ---
 
-## 🔍 Execution Trace
+### 🧰 Building Blocks
 
-```bash
+- **`Action`**: A single unit of async (or sync) logic
-[2025-04-14 10:33:22] DEBUG    [Step 1] ⚙ flaky_step()
+- **`ChainedAction`**: Execute a sequence of actions, with rollback and injection
-[2025-04-14 10:33:22] INFO     [Step 1] 🔁 Retrying (1/3) in 1.0s...
+- **`ActionGroup`**: Run actions concurrently and collect results
-[2025-04-14 10:33:23] DEBUG    [Step 1] ✅ Success | Result: ok
+- **`ProcessAction`**: Use `multiprocessing` for CPU-bound workflows
-[2025-04-14 10:33:23] DEBUG    [My Pipeline] ✅ Result: ['ok', 'ok']
+- **`Falyx`**: Interactive or headless CLI controller with history, menus, and theming
+- **`ExecutionContext`**: Metadata store per invocation (name, args, result, timing)
+- **`HookManager`**: Attach `before`, `after`, `on_success`, `on_error`, `on_teardown`
+
+---
+
+### 🔍 Logging
+```
+2025-07-20 09:29:32 [falyx] [INFO] Command 'R' selected.
+2025-07-20 09:29:32 [falyx] [INFO] [run_key] Executing: R — Run My Pipeline
+2025-07-20 09:29:33 [falyx] [INFO] [my_pipeline] Starting -> ChainedAction(name=my_pipeline, actions=['step_1', 'step_2'], args=(), kwargs={}, auto_inject=False, return_list=False)()
+2025-07-20 09:29:33 [falyx] [INFO] [step_1] Retrying (1/3) in 1.0s due to 'Random failure!'...
+2025-07-20 09:29:35 [falyx] [WARNING] [step_1] Retry attempt 1/3 failed due to 'Random failure!'.
+2025-07-20 09:29:35 [falyx] [INFO] [step_1] Retrying (2/3) in 2.0s due to 'Random failure!'...
+2025-07-20 09:29:37 [falyx] [INFO] [step_1] Retry succeeded on attempt 2.
+2025-07-20 09:29:37 [falyx] [INFO] [step_1] Recovered: step_1
+2025-07-20 09:29:37 [falyx] [DEBUG] [step_1] status=OK duration=3.627s result='ok' exception=None
+2025-07-20 09:29:37 [falyx] [INFO] [step_2] Retrying (1/3) in 1.0s due to 'Random failure!'...
+2025-07-20 09:29:38 [falyx] [WARNING] [step_2] Retry attempt 1/3 failed due to 'Random failure!'.
+2025-07-20 09:29:38 [falyx] [INFO] [step_2] Retrying (2/3) in 2.0s due to 'Random failure!'...
+2025-07-20 09:29:40 [falyx] [INFO] [step_2] Retry succeeded on attempt 2.
+2025-07-20 09:29:40 [falyx] [INFO] [step_2] Recovered: step_2
+2025-07-20 09:29:40 [falyx] [DEBUG] [step_2] status=OK duration=3.609s result='ok' exception=None
+2025-07-20 09:29:40 [falyx] [DEBUG] [my_pipeline] Success -> Result: 'ok'
+2025-07-20 09:29:40 [falyx] [DEBUG] [my_pipeline] Finished in 7.237s
+2025-07-20 09:29:40 [falyx] [DEBUG] [my_pipeline] status=OK duration=7.237s result='ok' exception=None
+2025-07-20 09:29:40 [falyx] [DEBUG] [Run My Pipeline] status=OK duration=7.238s result='ok' exception=None
 ```
 
----
+### 📊 History Tracking
 
-### 🧱 Core Building Blocks
+View full execution history:
 
-#### `Action`
+```bash
-A single async unit of work. Painless retry support.
+> history
+                                                   📊 Execution History
 
-#### `ChainedAction`
+   Index   Name                           Start         End    Duration   Status        Result / Exception
-Run tasks in sequence. Supports rollback on failure and context propagation.
+ ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+       0   step_1                      09:23:55    09:23:55      0.201s   ✅ Success    'ok'
+       1   step_2                      09:23:55    09:24:03      7.829s   ❌ Error      RuntimeError('Random failure!')
+       2   my_pipeline                 09:23:55    09:24:03      8.080s   ❌ Error      RuntimeError('Random failure!')
+       3   Run My Pipeline             09:23:55    09:24:03      8.082s   ❌ Error      RuntimeError('Random failure!')
+```
 
-#### `ActionGroup`
+Inspect result by index:
-Run tasks in parallel. Useful for fan-out operations like batch API calls.
 
-#### `ProcessAction`
+```bash
-Offload CPU-bound work to another process — no extra code needed.
+> history --result-index 0
+Action(name='step_1', action=flaky_step, args=(), kwargs={}, retry=True, rollback=False) ():
+ok
+```
 
-#### `Falyx`
+Print last result includes tracebacks:
-Your CLI controller — powers menus, subcommands, history, bottom bars, and more.
 
-#### `ExecutionContext`
+```bash
-Tracks metadata, arguments, timing, and results for each action execution.
+> history --last-result
-
+Command(key='R', description='Run My Pipeline' action='ChainedAction(name=my_pipeline, actions=['step_1', 'step_2'],
-#### `HookManager`
+args=(), kwargs={}, auto_inject=False, return_list=False)') ():
-Registers and triggers lifecycle hooks (`before`, `after`, `on_error`, etc.) for actions and commands.
+Traceback (most recent call last):
+  File ".../falyx/command.py", line 291, in __call__
+    result = await self.action(*combined_args, **combined_kwargs)
+             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File ".../falyx/action/base_action.py", line 91, in __call__
+    return await self._run(*args, **kwargs)
+           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File ".../falyx/action/chained_action.py", line 212, in _run
+    result = await prepared(*combined_args, **updated_kwargs)
+             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File ".../falyx/action/base_action.py", line 91, in __call__
+    return await self._run(*args, **kwargs)
+           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File ".../falyx/action/action.py", line 157, in _run
+    result = await self.action(*combined_args, **combined_kwargs)
+             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File ".../falyx/examples/simple.py", line 15, in flaky_step
+    raise RuntimeError("Random failure!")
+RuntimeError: Random failure!
+```
 
 ---
 
@@ -163,6 +222,6 @@ Registers and triggers lifecycle hooks (`before`, `after`, `on_error`, etc.) for
 
 > “Like a phalanx: organized, resilient, and reliable.”
 
-Falyx is designed for developers who don’t just want CLI tools to run — they want them to **fail meaningfully**, **recover gracefully**, and **log clearly**.
+Falyx is designed for developers who don’t just want CLI tools to run — they want them to **fail meaningfully**, **recover intentionally**, and **log clearly**.
 
 ---

examples/argument_examples.py

@@ -1,5 +1,6 @@
 import asyncio
 from enum import Enum
+from pathlib import Path
 
 from falyx import Falyx
 from falyx.action import Action
@@ -21,11 +22,27 @@ async def test_args(
     service: str,
     place: Place = Place.NEW_YORK,
     region: str = "us-east-1",
+    path: Path | None = None,
+    tag: str | None = None,
     verbose: bool | None = None,
+    numbers: list[int] | None = None,
+    just_a_bool: bool = False,
 ) -> str:
+    if numbers is None:
+        numbers = []
     if verbose:
-        print(f"Deploying {service} to {region} at {place}...")
+        print(
-    return f"{service} deployed to {region} at {place}"
+            f"Deploying {service}:{tag}:{"|".join(str(number) for number in numbers)} to {region} at {place} from {path}..."
+        )
+    return f"{service}:{tag}:{"|".join(str(number) for number in numbers)} deployed to {region} at {place} from {path}."
+
+
+async def test_path_arg(*paths: Path) -> str:
+    return f"Path argument received: {'|'.join(str(path) for path in paths)}"
+
+
+async def test_positional_numbers(*numbers: int) -> str:
+    return f"Positional numbers received: {', '.join(str(num) for num in numbers)}"
 
 
 def default_config(parser: CommandArgumentParser) -> None:
@@ -50,14 +67,87 @@ def default_config(parser: CommandArgumentParser) -> None:
         help="Deployment region.",
         choices=["us-east-1", "us-west-2", "eu-west-1"],
     )
+    parser.add_argument(
+        "-p",
+        "--path",
+        type=Path,
+        help="Path to the configuration file.",
+    )
     parser.add_argument(
         "--verbose",
         action="store_bool_optional",
         help="Enable verbose output.",
     )
+    parser.add_argument(
+        "-t",
+        "--tag",
+        type=str,
+        help="Optional tag for the deployment.",
+        suggestions=["latest", "stable", "beta"],
+    )
+    parser.add_argument(
+        "--numbers",
+        type=int,
+        nargs="*",
+        default=[1, 2, 3],
+        help="Optional number argument.",
+    )
+    parser.add_argument(
+        "-j",
+        "--just-a-bool",
+        action="store_true",
+        help="Just a boolean flag.",
+    )
+    parser.add_tldr_examples(
+        [
+            ("web", "Deploy 'web' to the default location (New York)"),
+            ("cache London --tag beta", "Deploy 'cache' to London with tag"),
+            ("database --region us-west-2 --verbose", "Verbose deploy to west region"),
+        ]
+    )
 
 
-flx = Falyx("Argument Examples")
+def path_config(parser: CommandArgumentParser) -> None:
+    """Argument configuration for path testing command."""
+    parser.add_argument(
+        "paths",
+        type=Path,
+        nargs="*",
+        help="One or more file or directory paths.",
+    )
+    parser.add_tldr_examples(
+        [
+            ("/path/to/file.txt", "Single file path"),
+            ("/path/to/dir1 /path/to/dir2", "Multiple directory paths"),
+            ("/path/with spaces/file.txt", "Path with spaces"),
+        ]
+    )
+
+
+def numbers_config(parser: CommandArgumentParser) -> None:
+    """Argument configuration for positional numbers testing command."""
+    parser.add_argument(
+        "numbers",
+        type=int,
+        nargs="*",
+        help="One or more integers.",
+    )
+    parser.add_tldr_examples(
+        [
+            ("1 2 3", "Three numbers"),
+            ("42", "Single number"),
+            ("", "No numbers"),
+        ]
+    )
+
+
+flx = Falyx(
+    "Argument Examples",
+    program="argument_examples.py",
+    hide_menu_table=True,
+    show_placeholder_menu=True,
+    enable_prompt_history=True,
+)
 
 flx.add_command(
     key="T",
@@ -68,7 +158,34 @@ flx.add_command(
         name="test_args",
         action=test_args,
     ),
+    style="bold #B3EBF2",
     argument_config=default_config,
 )
 
+flx.add_command(
+    key="P",
+    aliases=["path"],
+    description="Path Command",
+    help_text="A command to test path argument parsing.",
+    action=Action(
+        name="test_path_arg",
+        action=test_path_arg,
+    ),
+    style="bold #F2B3EB",
+    argument_config=path_config,
+)
+
+flx.add_command(
+    key="N",
+    aliases=["numbers"],
+    description="Numbers Command",
+    help_text="A command to test positional numbers argument parsing.",
+    action=Action(
+        name="test_positional_numbers",
+        action=test_positional_numbers,
+    ),
+    style="bold #F2F2B3",
+    argument_config=numbers_config,
+)
+
 asyncio.run(flx.run())

examples/confirm_example.py

@@ -70,7 +70,7 @@ async def build_chain(dogs: list[Dog]) -> ChainedAction:
             ),
             ConfirmAction(
                 name="test_confirm",
-                message="Do you want to process the dogs?",
+                prompt_message="Do you want to process the dogs?",
                 confirm_type="yes_no_cancel",
                 return_last_result=True,
                 inject_into="dogs",
@@ -101,10 +101,16 @@ def dog_config(parser: CommandArgumentParser) -> None:
         lazy_resolver=False,
         help="List of dogs to process.",
     )
+    parser.add_tldr_examples(
+        [
+            ("max", "Process the dog named Max"),
+            ("bella buddy max", "Process the dogs named Bella, Buddy, and Max"),
+        ]
+    )
 
 
 async def main():
-    flx = Falyx("Save Dogs Example")
+    flx = Falyx("Save Dogs Example", program="confirm_example.py")
 
     flx.add_command(
         key="D",

examples/falyx_demo.py

@@ -84,7 +84,7 @@ async def main() -> None:
 
     # --- Bottom bar info ---
     flx.bottom_bar.columns = 3
-    flx.bottom_bar.add_toggle_from_option("V", "Verbose", flx.options, "verbose")
+    flx.bottom_bar.add_toggle_from_option("B", "Verbose", flx.options, "verbose")
     flx.bottom_bar.add_toggle_from_option("U", "Debug Hooks", flx.options, "debug_hooks")
     flx.bottom_bar.add_static("Version", f"Falyx v{__version__}")
 

examples/file_select.py

@@ -19,6 +19,8 @@ flx = Falyx(
     description="This example demonstrates how to select files using Falyx.",
     version="1.0.0",
     program="file_select.py",
+    hide_menu_table=True,
+    show_placeholder_menu=True,
 )
 
 flx.add_command(

examples/pipeline_demo.py

@@ -1,59 +1,92 @@
 import asyncio
+import random
+import time
 
-from falyx import ExecutionRegistry as er
+from falyx import Falyx
 from falyx.action import Action, ActionGroup, ChainedAction, ProcessAction
-from falyx.retry import RetryHandler, RetryPolicy
+from falyx.console import console
 
 
 # Step 1: Fast I/O-bound setup (standard Action)
 async def checkout_code():
-    print("📥 Checking out code...")
+    console.print("🔄 Checking out code...")
     await asyncio.sleep(0.5)
+    console.print("📦 Code checked out successfully.")
 
 
 # Step 2: CPU-bound task (ProcessAction)
 def run_static_analysis():
-    print("🧠 Running static analysis (CPU-bound)...")
     total = 0
     for i in range(10_000_000):
         total += i % 3
+    time.sleep(2)
     return total
 
 
 # Step 3: Simulated flaky test with retry
 async def flaky_tests():
-    import random
+    console.print("🧪 Running tests...")
-
     await asyncio.sleep(0.3)
     if random.random() < 0.3:
         raise RuntimeError("❌ Random test failure!")
-    print("🧪 Tests passed.")
+    console.print("🧪 Tests passed.")
     return "ok"
 
 
 # Step 4: Multiple deploy targets (parallel ActionGroup)
 async def deploy_to(target: str):
-    print(f"🚀 Deploying to {target}...")
+    console.print(f"🚀 Deploying to {target}...")
-    await asyncio.sleep(0.2)
+    await asyncio.sleep(random.randint(2, 6))
+    console.print(f"✅ Deployment to {target} complete.")
     return f"{target} complete"
 
 
 def build_pipeline():
-    retry_handler = RetryHandler(RetryPolicy(max_retries=3, delay=0.5))
-
     # Base actions
     checkout = Action("Checkout", checkout_code)
-    analysis = ProcessAction("Static Analysis", run_static_analysis)
+    analysis = ProcessAction(
-    tests = Action("Run Tests", flaky_tests)
+        "Static Analysis",
-    tests.hooks.register("on_error", retry_handler.retry_on_error)
+        run_static_analysis,
+        spinner=True,
+        spinner_message="Analyzing code...",
+    )
+    analysis.hooks.register(
+        "before", lambda ctx: console.print("🧠 Running static analysis (CPU-bound)...")
+    )
+    analysis.hooks.register("after", lambda ctx: console.print("🧠 Analysis complete!"))
+    tests = Action(
+        "Run Tests",
+        flaky_tests,
+        retry=True,
+        spinner=True,
+        spinner_message="Running tests...",
+    )
 
     # Parallel deploys
     deploy_group = ActionGroup(
         "Deploy to All",
         [
-            Action("Deploy US", deploy_to, args=("us-west",)),
+            Action(
-            Action("Deploy EU", deploy_to, args=("eu-central",)),
+                "Deploy US",
-            Action("Deploy Asia", deploy_to, args=("asia-east",)),
+                deploy_to,
+                args=("us-west",),
+                spinner=True,
+                spinner_message="Deploying US...",
+            ),
+            Action(
+                "Deploy EU",
+                deploy_to,
+                args=("eu-central",),
+                spinner=True,
+                spinner_message="Deploying EU...",
+            ),
+            Action(
+                "Deploy Asia",
+                deploy_to,
+                args=("asia-east",),
+                spinner=True,
+                spinner_message="Deploying Asia...",
+            ),
         ],
     )
 
@@ -66,10 +99,22 @@ pipeline = build_pipeline()
 
 # Run the pipeline
 async def main():
-    pipeline = build_pipeline()
+
-    await pipeline()
+    flx = Falyx(
-    er.summary()
+        hide_menu_table=True, program="pipeline_demo.py", show_placeholder_menu=True
-    await pipeline.preview()
+    )
+    flx.add_command(
+        "P",
+        "Run Pipeline",
+        pipeline,
+        spinner=True,
+        spinner_type="line",
+        spinner_message="Running pipeline...",
+        tags=["pipeline", "demo"],
+        help_text="Run the full CI/CD pipeline demo.",
+    )
+
+    await flx.run()
 
 
 if __name__ == "__main__":

examples/simple.py

@@ -11,15 +11,15 @@ setup_logging()
 # A flaky async step that fails randomly
 async def flaky_step() -> str:
     await asyncio.sleep(0.2)
-    if random.random() < 0.3:
+    if random.random() < 0.5:
         raise RuntimeError("Random failure!")
-    print("Flaky step succeeded!")
+    print("ok")
     return "ok"
 
 
 # Create a retry handler
-step1 = Action(name="step_1", action=flaky_step, retry=True)
+step1 = Action(name="step_1", action=flaky_step)
-step2 = Action(name="step_2", action=flaky_step, retry=True)
+step2 = Action(name="step_2", action=flaky_step)
 
 # Chain the actions
 chain = ChainedAction(name="my_pipeline", actions=[step1, step2])
@@ -33,6 +33,8 @@ falyx.add_command(
     logging_hooks=True,
     preview_before_confirm=True,
     confirm=True,
+    retry_all=True,
+    spinner=True,
 )
 
 # Entry point

examples/user_input_demo.py

@@ -22,7 +22,7 @@ chain = ChainedAction(
         "Name",
         UserInputAction(
             name="User Input",
-            prompt_text="Enter your {last_result}: ",
+            prompt_message="Enter your {last_result}: ",
             validator=validate_alpha(),
         ),
         Action(

falyx/__init__.py

@@ -1,7 +1,6 @@
-"""
+"""Falyx CLI Framework
-Falyx CLI Framework
 
-Copyright (c) 2025 rtj.dev LLC.
+Copyright (c) 2026 rtj.dev LLC.
 Licensed under the MIT License. See LICENSE file for details.
 """
 

falyx/__main__.py

@@ -1,20 +1,18 @@
-"""
+"""Falyx CLI Framework
-Falyx CLI Framework
 
-Copyright (c) 2025 rtj.dev LLC.
+Copyright (c) 2026 rtj.dev LLC.
 Licensed under the MIT License. See LICENSE file for details.
 """
 
 import asyncio
 import os
 import sys
-from argparse import ArgumentParser, Namespace, _SubParsersAction
 from pathlib import Path
 from typing import Any
 
 from falyx.config import loader
 from falyx.falyx import Falyx
-from falyx.parser import CommandArgumentParser, get_root_parser, get_subparsers
+from falyx.parser import CommandArgumentParser
 
 
 def find_falyx_config() -> Path | None:
@@ -49,48 +47,11 @@ def init_config(parser: CommandArgumentParser) -> None:
     )
 
 
-def init_callback(args: Namespace) -> None:
+def build_bootstrap_falyx() -> Falyx:
-    """Callback for the init command."""
-    if args.command == "init":
-        from falyx.init import init_project
-
-        init_project(args.name)
-    elif args.command == "init_global":
-        from falyx.init import init_global
-
-        init_global()
-
-
-def get_parsers() -> tuple[ArgumentParser, _SubParsersAction]:
-    root_parser: ArgumentParser = get_root_parser()
-    subparsers = get_subparsers(root_parser)
-    init_parser = subparsers.add_parser(
-        "init",
-        help="Initialize a new Falyx project",
-        description="Create a new Falyx project with mock configuration files.",
-        epilog="If no name is provided, the current directory will be used.",
-    )
-    init_parser.add_argument(
-        "name",
-        type=str,
-        help="Name of the new Falyx project",
-        default=".",
-        nargs="?",
-    )
-    subparsers.add_parser(
-        "init-global",
-        help="Initialize Falyx global configuration",
-        description="Create a global Falyx configuration at ~/.config/falyx/.",
-    )
-    return root_parser, subparsers
-
-
-def main() -> Any:
-    bootstrap_path = bootstrap()
-    if not bootstrap_path:
     from falyx.init import init_global, init_project
 
-        flx: Falyx = Falyx()
+    flx = Falyx()
+
     flx.add_command(
         "I",
         "Initialize a new Falyx project",
@@ -106,14 +67,19 @@ def main() -> Any:
         aliases=["init-global"],
         help_text="Create a global Falyx configuration at ~/.config/falyx/.",
     )
-    else:
+    return flx
-        flx = loader(bootstrap_path)
 
-    root_parser, subparsers = get_parsers()
 
-    return asyncio.run(
+def build_falyx() -> Falyx:
-        flx.run(root_parser=root_parser, subparsers=subparsers, callback=init_callback)
+    bootstrap_path = bootstrap()
-    )
+    if bootstrap_path:
+        return loader(bootstrap_path)
+    return build_bootstrap_falyx()
+
+
+def main() -> Any:
+    flx = build_falyx()
+    return asyncio.run(flx.run())
 
 
 if __name__ == "__main__":

falyx/action/__init__.py

@@ -1,7 +1,6 @@
-"""
+"""Falyx CLI Framework
-Falyx CLI Framework
 
-Copyright (c) 2025 rtj.dev LLC.
+Copyright (c) 2026 rtj.dev LLC.
 Licensed under the MIT License. See LICENSE file for details.
 """
 

falyx/action/action.py

@@ -1,5 +1,37 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""action.py"""
+"""Defines `Action`, the core atomic unit in the Falyx CLI framework, used to wrap and
+execute a single callable or coroutine with structured lifecycle support.
+
+An `Action` is the simplest building block in Falyx's execution model, enabling
+developers to turn ordinary Python functions into hookable, retryable, introspectable
+workflow steps. It supports synchronous or asynchronous callables, argument injection,
+rollback handlers, and retry policies.
+
+Key Features:
+- Lifecycle hooks: `before`, `on_success`, `on_error`, `after`, `on_teardown`
+- Optional `last_result` injection for chained workflows
+- Retry logic via configurable `RetryPolicy` and `RetryHandler`
+- Rollback function support for recovery and undo behavior
+- Rich preview output for introspection and dry-run diagnostics
+
+Usage Scenarios:
+- Wrapping business logic, utility functions, or external API calls
+- Converting lightweight callables into structured CLI actions
+- Composing workflows using `Action`, `ChainedAction`, or `ActionGroup`
+
+Example:
+    def compute(x, y):
+        return x + y
+
+    Action(
+        name="AddNumbers",
+        action=compute,
+        args=(2, 3),
+    )
+
+This module serves as the foundation for building robust, observable,
+and composable CLI automation flows in Falyx.
+"""
 from __future__ import annotations
 
 from typing import Any, Awaitable, Callable
@@ -17,8 +49,7 @@ from falyx.utils import ensure_async
 
 
 class Action(BaseAction):
-    """
+    """Action wraps a simple function or coroutine into a standard executable unit.
-    Action wraps a simple function or coroutine into a standard executable unit.
 
     It supports:
     - Optional retry logic.
@@ -27,11 +58,11 @@ class Action(BaseAction):
     - Optional rollback handlers for undo logic.
 
     Args:
-        name (str): Name of the action.
+        name (str): Name of the action. Used for logging and debugging.
         action (Callable): The function or coroutine to execute.
         rollback (Callable, optional): Rollback function to undo the action.
-        args (tuple, optional): Static positional arguments.
+        args (tuple, optional): Positional arguments.
-        kwargs (dict, optional): Static keyword arguments.
+        kwargs (dict, optional): Keyword arguments.
         hooks (HookManager, optional): Hook manager for lifecycle events.
         inject_last_result (bool, optional): Enable last_result injection.
         inject_into (str, optional): Name of injected key.
@@ -50,14 +81,28 @@ class Action(BaseAction):
         hooks: HookManager | None = None,
         inject_last_result: bool = False,
         inject_into: str = "last_result",
+        never_prompt: bool | None = None,
+        logging_hooks: bool = False,
         retry: bool = False,
         retry_policy: RetryPolicy | None = None,
+        spinner: bool = False,
+        spinner_message: str = "Processing...",
+        spinner_type: str = "dots",
+        spinner_style: str = OneColors.CYAN,
+        spinner_speed: float = 1.0,
     ) -> None:
         super().__init__(
             name,
             hooks=hooks,
             inject_last_result=inject_last_result,
             inject_into=inject_into,
+            never_prompt=never_prompt,
+            logging_hooks=logging_hooks,
+            spinner=spinner,
+            spinner_message=spinner_message,
+            spinner_type=spinner_type,
+            spinner_style=spinner_style,
+            spinner_speed=spinner_speed,
         )
         self.action = action
         self.rollback = rollback
@@ -101,8 +146,8 @@ class Action(BaseAction):
             self.enable_retry()
 
     def get_infer_target(self) -> tuple[Callable[..., Any], None]:
-        """
+        """Returns the callable to be used for argument inference.
-        Returns the callable to be used for argument inference.
+
         By default, it returns the action itself.
         """
         return self.action, None
@@ -157,6 +202,7 @@ class Action(BaseAction):
         return (
             f"Action(name={self.name!r}, action="
             f"{getattr(self._action, '__name__', repr(self._action))}, "
+            f"args={self.args!r}, kwargs={self.kwargs!r}, "
             f"retry={self.retry_policy.enabled}, "
             f"rollback={self.rollback is not None})"
         )

falyx/action/action_factory.py

@@ -1,5 +1,35 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""action_factory_action.py"""
+"""Defines `ActionFactory`, a dynamic Falyx Action that defers the construction of its
+underlying logic to runtime using a user-defined factory function.
+
+This pattern is useful when the specific Action to execute cannot be determined until
+execution time—such as when branching on data, generating parameterized HTTP requests,
+or selecting configuration-aware flows. `ActionFactory` integrates seamlessly with the
+Falyx lifecycle system and supports hook propagation, teardown registration, and
+contextual previewing.
+
+Key Features:
+- Accepts a factory function that returns a `BaseAction` instance
+- Supports injection of `last_result` and arbitrary args/kwargs
+- Integrates into chained or standalone workflows
+- Automatically previews generated action tree
+- Propagates shared context and teardown hooks to the returned action
+
+Common Use Cases:
+- Conditional or data-driven action generation
+- Configurable workflows with dynamic behavior
+- Adapter for factory-style dependency injection in CLI flows
+
+Example:
+    def generate_request_action(env):
+        return HTTPAction(f"GET /status/{env}", url=f"https://api/{env}/status")
+
+    ActionFactory(
+        name="GetEnvStatus",
+        factory=generate_request_action,
+        inject_last_result=True,
+    )
+"""
 from typing import Any, Callable
 
 from rich.tree import Tree
@@ -15,17 +45,20 @@ from falyx.utils import ensure_async
 
 
 class ActionFactory(BaseAction):
-    """
+    """Dynamically creates and runs another Action at runtime using a factory function.
-    Dynamically creates and runs another Action at runtime using a factory function.
 
     This is useful for generating context-specific behavior (e.g., dynamic HTTPActions)
     where the structure of the next action depends on runtime values.
 
     Args:
-        name (str): Name of the action.
+        name (str): Name of the action. Used for logging and debugging.
         factory (Callable): A function that returns a BaseAction given args/kwargs.
         inject_last_result (bool): Whether to inject last_result into the factory.
         inject_into (str): The name of the kwarg to inject last_result as.
+        args (tuple, optional): Positional arguments for the factory.
+        kwargs (dict, optional): Keyword arguments for the factory.
+        preview_args (tuple, optional): Positional arguments for the preview.
+        preview_kwargs (dict, optional): Keyword arguments for the preview.
     """
 
     def __init__(
@@ -133,3 +166,11 @@ class ActionFactory(BaseAction):
 
         if not parent:
             self.console.print(tree)
+
+    def __str__(self) -> str:
+        return (
+            f"ActionFactory(name={self.name!r}, "
+            f"inject_last_result={self.inject_last_result}, "
+            f"factory={self._factory.__name__ if hasattr(self._factory, '__name__') else type(self._factory).__name__}, "
+            f"args={self.args!r}, kwargs={self.kwargs!r})"
+        )

falyx/action/action_group.py

@@ -1,5 +1,38 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""action_group.py"""
+"""Defines `ActionGroup`, a Falyx Action that executes multiple sub-actions concurrently
+using asynchronous concurrency.
+
+`ActionGroup` is designed for workflows where several independent actions can run
+simultaneously to improve responsiveness and reduce latency. It ensures robust error
+isolation, shared result tracking, and full lifecycle hook integration while preserving
+Falyx's introspectability and chaining capabilities.
+
+Key Features:
+- Executes all actions concurrently via `asyncio.gather`
+- Aggregates results as a list of `(name, result)` tuples
+- Collects and reports multiple errors without interrupting execution
+- Compatible with `SharedContext`, `OptionsManager`, and `last_result` injection
+- Teardown-aware: propagates teardown registration across all child actions
+- Fully previewable via Rich tree rendering
+
+Use Cases:
+- Batch execution of independent tasks (e.g., multiple file operations, API calls)
+- Concurrent report generation or validations
+- High-throughput CLI pipelines where latency is critical
+
+Raises:
+- `EmptyGroupError`: If no actions are added to the group
+- `Exception`: Summarizes all failed actions after execution
+
+Example:
+    ActionGroup(
+        name="ConcurrentChecks",
+        actions=[Action(...), Action(...), ChainedAction(...)],
+    )
+
+This module complements `ChainedAction` by offering breadth-wise (concurrent) execution
+as opposed to depth-wise (sequential) execution.
+"""
 import asyncio
 import random
 from typing import Any, Awaitable, Callable, Sequence
@@ -20,14 +53,13 @@ from falyx.themes.colors import OneColors
 
 
 class ActionGroup(BaseAction, ActionListMixin):
-    """
+    """ActionGroup executes multiple actions concurrently.
-    ActionGroup executes multiple actions concurrently in parallel.
 
     It is ideal for independent tasks that can be safely run simultaneously,
     improving overall throughput and responsiveness of workflows.
 
     Core features:
-    - Parallel execution of all contained actions.
+    - Concurrent execution of all contained actions.
     - Shared last_result injection across all actions if configured.
     - Aggregated collection of individual results as (name, result) pairs.
     - Hook lifecycle support (before, on_success, on_error, after, on_teardown).
@@ -41,12 +73,14 @@ class ActionGroup(BaseAction, ActionListMixin):
 
     Best used for:
     - Batch processing multiple independent tasks.
-    - Reducing latency for workflows with parallelizable steps.
+    - Reducing latency for workflows with concurrent steps.
     - Isolating errors while maximizing successful execution.
 
     Args:
         name (str): Name of the chain.
         actions (list): List of actions or literals to execute.
+        args (tuple, optional): Positional arguments.
+        kwargs (dict, optional): Keyword arguments.
         hooks (HookManager, optional): Hooks for lifecycle events.
         inject_last_result (bool, optional): Whether to inject last results into kwargs
                                              by default.
@@ -65,12 +99,26 @@ class ActionGroup(BaseAction, ActionListMixin):
         hooks: HookManager | None = None,
         inject_last_result: bool = False,
         inject_into: str = "last_result",
+        never_prompt: bool | None = None,
+        logging_hooks: bool = False,
+        spinner: bool = False,
+        spinner_message: str = "Processing...",
+        spinner_type: str = "dots",
+        spinner_style: str = OneColors.CYAN,
+        spinner_speed: float = 1.0,
     ):
         super().__init__(
             name,
             hooks=hooks,
             inject_last_result=inject_last_result,
             inject_into=inject_into,
+            never_prompt=never_prompt,
+            logging_hooks=logging_hooks,
+            spinner=spinner,
+            spinner_message=spinner_message,
+            spinner_type=spinner_type,
+            spinner_style=spinner_style,
+            spinner_speed=spinner_speed,
         )
         ActionListMixin.__init__(self)
         self.args = args
@@ -123,7 +171,7 @@ class ActionGroup(BaseAction, ActionListMixin):
         combined_args = args + self.args
         combined_kwargs = {**self.kwargs, **kwargs}
 
-        shared_context = SharedContext(name=self.name, action=self, is_parallel=True)
+        shared_context = SharedContext(name=self.name, action=self, is_concurrent=True)
         if self.shared_context:
             shared_context.set_shared_result(self.shared_context.last_result())
         updated_kwargs = self._maybe_inject_last_result(combined_kwargs)
@@ -179,7 +227,7 @@ class ActionGroup(BaseAction, ActionListMixin):
             action.register_hooks_recursively(hook_type, hook)
 
     async def preview(self, parent: Tree | None = None):
-        label = [f"[{OneColors.MAGENTA_b}]⏩ ActionGroup (parallel)[/] '{self.name}'"]
+        label = [f"[{OneColors.MAGENTA_b}]⏩ ActionGroup (concurrent)[/] '{self.name}'"]
         if self.inject_last_result:
             label.append(f" [dim](receives '{self.inject_into}')[/dim]")
         tree = parent.add("".join(label)) if parent else Tree("".join(label))
@@ -191,7 +239,8 @@ class ActionGroup(BaseAction, ActionListMixin):
 
     def __str__(self):
         return (
-            f"ActionGroup(name={self.name!r}, actions={[a.name for a in self.actions]!r},"
+            f"ActionGroup(name={self.name}, actions={[a.name for a in self.actions]}, "
-            f" inject_last_result={self.inject_last_result}, "
+            f"args={self.args!r}, kwargs={self.kwargs!r}, "
-            f"inject_into={self.inject_into!r})"
+            f"inject_last_result={self.inject_last_result}, "
+            f"inject_into={self.inject_into})"
         )

falyx/action/action_mixins.py

@@ -1,12 +1,34 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""action_mixins.py"""
+"""Provides reusable mixins for managing collections of `BaseAction` instances
-from typing import Sequence
+within composite Falyx actions such as `ActionGroup` or `ChainedAction`.
+
+The primary export, `ActionListMixin`, encapsulates common functionality for
+maintaining a mutable list of named actions—such as adding, removing, or retrieving
+actions by name—without duplicating logic across composite action types.
+"""
+
+from typing import Any, Sequence
 
 from falyx.action.base_action import BaseAction
 
 
 class ActionListMixin:
-    """Mixin for managing a list of actions."""
+    """
+    Mixin for managing a list of named `BaseAction` objects.
+
+    Provides helper methods for setting, adding, removing, checking, and
+    retrieving actions in composite Falyx constructs like `ActionGroup`.
+
+    Attributes:
+        actions (list[BaseAction]): The internal list of managed actions.
+
+    Methods:
+        set_actions(actions): Replaces all current actions with the given list.
+        add_action(action): Adds a new action to the list.
+        remove_action(name): Removes an action by its name.
+        has_action(name): Returns True if an action with the given name exists.
+        get_action(name): Returns the action matching the name, or None.
+    """
 
     def __init__(self) -> None:
         self.actions: list[BaseAction] = []
@@ -22,7 +44,7 @@ class ActionListMixin:
         self.actions.append(action)
 
     def remove_action(self, name: str) -> None:
-        """Removes an action by name."""
+        """Removes all actions with the given name."""
         self.actions = [action for action in self.actions if action.name != name]
 
     def has_action(self, name: str) -> bool:
@@ -30,7 +52,7 @@ class ActionListMixin:
         return any(action.name == name for action in self.actions)
 
     def get_action(self, name: str) -> BaseAction | None:
-        """Retrieves an action by name."""
+        """Retrieves a single action with the given name."""
         for action in self.actions:
             if action.name == name:
                 return action

falyx/action/action_types.py

@@ -1,12 +1,51 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""action_types.py"""
+"""Defines strongly-typed enums used throughout the Falyx CLI framework for
+representing common structured values like file formats, selection return types,
+and confirmation modes.
+
+These enums support alias resolution, graceful coercion from string inputs,
+and are used for input validation, serialization, and CLI configuration parsing.
+
+Exports:
+- FileType: Defines supported file formats for `LoadFileAction` and `SaveFileAction`
+- SelectionReturnType: Defines structured return modes for `SelectionAction`
+- ConfirmType: Defines selectable confirmation types for prompts and guards
+
+Key Features:
+- Custom `_missing_()` methods for forgiving string coercion and error reporting
+- Aliases and normalization support for user-friendly config-driven workflows
+- Useful in CLI flag parsing, YAML configs, and dynamic schema validation
+
+Example:
+    FileType("yml") → FileType.YAML
+    SelectionReturnType("value") → SelectionReturnType.VALUE
+    ConfirmType("YES_NO") → ConfirmType.YES_NO
+"""
 from __future__ import annotations
 
 from enum import Enum
 
 
 class FileType(Enum):
-    """Enum for file return types."""
+    """Represents supported file types for reading and writing in Falyx Actions.
+
+    Used by `LoadFileAction` and `SaveFileAction` to determine how to parse or
+    serialize file content. Includes alias resolution for common extensions like
+    `.yml`, `.txt`, and `filepath`.
+
+    Members:
+        TEXT: Raw encoded text as a string.
+        PATH: Returns the file path (as a Path object).
+        JSON: JSON-formatted object.
+        TOML: TOML-formatted object.
+        YAML: YAML-formatted object.
+        CSV: List of rows (as lists) from a CSV file.
+        TSV: Same as CSV, but tab-delimited.
+        XML: Raw XML as a ElementTree.
+
+    Example:
+        FileType("yml")  → FileType.YAML
+    """
 
     TEXT = "text"
     PATH = "path"
@@ -17,6 +56,11 @@ class FileType(Enum):
     TSV = "tsv"
     XML = "xml"
 
+    @classmethod
+    def choices(cls) -> list[FileType]:
+        """Return a list of all hook type choices."""
+        return list(cls)
+
     @classmethod
     def _get_alias(cls, value: str) -> str:
         aliases = {
@@ -29,18 +73,37 @@ class FileType(Enum):
 
     @classmethod
     def _missing_(cls, value: object) -> FileType:
-        if isinstance(value, str):
+        if not isinstance(value, str):
-            normalized = value.lower()
+            raise ValueError(f"Invalid {cls.__name__}: {value!r}")
+        normalized = value.strip().lower()
         alias = cls._get_alias(normalized)
         for member in cls:
             if member.value == alias:
                 return member
         valid = ", ".join(member.value for member in cls)
-        raise ValueError(f"Invalid FileType: '{value}'. Must be one of: {valid}")
+        raise ValueError(f"Invalid {cls.__name__}: '{value}'. Must be one of: {valid}")
+
+    def __str__(self) -> str:
+        """Return the string representation of the confirm type."""
+        return self.value
 
 
 class SelectionReturnType(Enum):
-    """Enum for dictionary return types."""
+    """Controls what is returned from a `SelectionAction` when using a selection map.
+
+    Determines how the user's choice(s) from a `dict[str, SelectionOption]` are
+    transformed and returned by the action.
+
+    Members:
+        KEY: Return the selected key(s) only.
+        VALUE: Return the value(s) associated with the selected key(s).
+        DESCRIPTION: Return the description(s) of the selected item(s).
+        DESCRIPTION_VALUE: Return a dict of {description: value} pairs.
+        ITEMS: Return full `SelectionOption` objects as a dict {key: SelectionOption}.
+
+    Example:
+        return_type=SelectionReturnType.VALUE  → returns raw values like 'prod'
+    """
 
     KEY = "key"
     VALUE = "value"
@@ -48,14 +111,53 @@ class SelectionReturnType(Enum):
     DESCRIPTION_VALUE = "description_value"
     ITEMS = "items"
 
+    @classmethod
+    def choices(cls) -> list[SelectionReturnType]:
+        """Return a list of all hook type choices."""
+        return list(cls)
+
+    @classmethod
+    def _get_alias(cls, value: str) -> str:
+        aliases = {
+            "desc": "description",
+            "desc_value": "description_value",
+        }
+        return aliases.get(value, value)
+
     @classmethod
     def _missing_(cls, value: object) -> SelectionReturnType:
+        if not isinstance(value, str):
+            raise ValueError(f"Invalid {cls.__name__}: {value!r}")
+        normalized = value.strip().lower()
+        alias = cls._get_alias(normalized)
+        for member in cls:
+            if member.value == alias:
+                return member
         valid = ", ".join(member.value for member in cls)
-        raise ValueError(f"Invalid DictReturnType: '{value}'. Must be one of: {valid}")
+        raise ValueError(f"Invalid {cls.__name__}: '{value}'. Must be one of: {valid}")
+
+    def __str__(self) -> str:
+        """Return the string representation of the confirm type."""
+        return self.value
 
 
 class ConfirmType(Enum):
-    """Enum for different confirmation types."""
+    """Enum for defining prompt styles in confirmation dialogs.
+
+    Used by confirmation actions to control user input behavior and available choices.
+
+    Members:
+        YES_NO: Prompt with Yes / No options.
+        YES_CANCEL: Prompt with Yes / Cancel options.
+        YES_NO_CANCEL: Prompt with Yes / No / Cancel options.
+        TYPE_WORD: Require user to type a specific confirmation word (e.g., "delete").
+        TYPE_WORD_CANCEL: Same as TYPE_WORD, but allows cancellation.
+        OK_CANCEL: Prompt with OK / Cancel options.
+        ACKNOWLEDGE: Single confirmation button (e.g., "Acknowledge").
+
+    Example:
+        ConfirmType("yes_no_cancel") → ConfirmType.YES_NO_CANCEL
+    """
 
     YES_NO = "yes_no"
     YES_CANCEL = "yes_cancel"
@@ -70,15 +172,30 @@ class ConfirmType(Enum):
         """Return a list of all hook type choices."""
         return list(cls)
 
-    def __str__(self) -> str:
+    @classmethod
-        """Return the string representation of the confirm type."""
+    def _get_alias(cls, value: str) -> str:
-        return self.value
+        aliases = {
+            "yes": "yes_no",
+            "ok": "ok_cancel",
+            "type": "type_word",
+            "word": "type_word",
+            "word_cancel": "type_word_cancel",
+            "ack": "acknowledge",
+        }
+        return aliases.get(value, value)
 
     @classmethod
     def _missing_(cls, value: object) -> ConfirmType:
-        if isinstance(value, str):
+        if not isinstance(value, str):
+            raise ValueError(f"Invalid {cls.__name__}: {value!r}")
+        normalized = value.strip().lower()
+        alias = cls._get_alias(normalized)
         for member in cls:
-                if member.value == value.lower():
+            if member.value == alias:
                 return member
         valid = ", ".join(member.value for member in cls)
-        raise ValueError(f"Invalid ConfirmType: '{value}'. Must be one of: {valid}")
+        raise ValueError(f"Invalid {cls.__name__}: '{value}'. Must be one of: {valid}")
+
+    def __str__(self) -> str:
+        """Return the string representation of the confirm type."""
+        return self.value

falyx/action/base_action.py

@@ -1,7 +1,5 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""base_action.py
+"""Core action system for Falyx.
-
-Core action system for Falyx.
 
 This module defines the building blocks for executable actions and workflows,
 providing a structured way to compose, execute, recover, and manage sequences of
@@ -15,13 +13,13 @@ Core guarantees:
 - Consistent timing and execution context tracking for each run.
 - Unified, predictable result handling and error propagation.
 - Optional last_result injection to enable flexible, data-driven workflows.
-- Built-in support for retries, rollbacks, parallel groups, chaining, and fallback
+- Built-in support for retries, rollbacks, concurrent groups, chaining, and fallback
   recovery.
 
 Key components:
 - Action: wraps a function or coroutine into a standard executable unit.
 - ChainedAction: runs actions sequentially, optionally injecting last results.
-- ActionGroup: runs actions in parallel and gathers results.
+- ActionGroup: runs actions concurrently and gathers results.
 - ProcessAction: executes CPU-bound functions in a separate process.
 - LiteralInputAction: injects static values into workflows.
 - FallbackAction: gracefully recovers from failures or missing data.
@@ -40,20 +38,27 @@ from falyx.console import console
 from falyx.context import SharedContext
 from falyx.debug import register_debug_hooks
 from falyx.hook_manager import Hook, HookManager, HookType
+from falyx.hooks import spinner_before_hook, spinner_teardown_hook
 from falyx.logger import logger
 from falyx.options_manager import OptionsManager
+from falyx.themes import OneColors
 
 
 class BaseAction(ABC):
-    """
+    """Base class for actions. Actions can be simple functions or more
-    Base class for actions. Actions can be simple functions or more
     complex actions like `ChainedAction` or `ActionGroup`. They can also
     be run independently or as part of Falyx.
 
+    Args:
+        name (str): Name of the action. Used for logging and debugging.
+        hooks (HookManager | None): Hook manager for lifecycle events.
         inject_last_result (bool): Whether to inject the previous action's result
                                    into kwargs.
         inject_into (str): The name of the kwarg key to inject the result as
                            (default: 'last_result').
+        never_prompt (bool | None): Whether to never prompt for input.
+        logging_hooks (bool): Whether to register debug hooks for logging.
+        ignore_in_history (bool): Whether to ignore this action in execution history last result.
     """
 
     def __init__(
@@ -63,8 +68,14 @@ class BaseAction(ABC):
         hooks: HookManager | None = None,
         inject_last_result: bool = False,
         inject_into: str = "last_result",
-        never_prompt: bool = False,
+        never_prompt: bool | None = None,
         logging_hooks: bool = False,
+        ignore_in_history: bool = False,
+        spinner: bool = False,
+        spinner_message: str = "Processing...",
+        spinner_type: str = "dots",
+        spinner_style: str = OneColors.CYAN,
+        spinner_speed: float = 1.0,
     ) -> None:
         self.name = name
         self.hooks = hooks or HookManager()
@@ -72,10 +83,19 @@ class BaseAction(ABC):
         self.shared_context: SharedContext | None = None
         self.inject_last_result: bool = inject_last_result
         self.inject_into: str = inject_into
-        self._never_prompt: bool = never_prompt
+        self._never_prompt: bool | None = never_prompt
         self._skip_in_chain: bool = False
         self.console: Console = console
         self.options_manager: OptionsManager | None = None
+        self.ignore_in_history: bool = ignore_in_history
+        self.spinner_message = spinner_message
+        self.spinner_type = spinner_type
+        self.spinner_style = spinner_style
+        self.spinner_speed = spinner_speed
+
+        if spinner:
+            self.hooks.register(HookType.BEFORE, spinner_before_hook)
+            self.hooks.register(HookType.ON_TEARDOWN, spinner_teardown_hook)
 
         if logging_hooks:
             register_debug_hooks(self.hooks)
@@ -93,8 +113,8 @@ class BaseAction(ABC):
 
     @abstractmethod
     def get_infer_target(self) -> tuple[Callable[..., Any] | None, dict[str, Any] | None]:
-        """
+        """Returns the callable to be used for argument inference.
-        Returns the callable to be used for argument inference.
+
         By default, it returns None.
         """
         raise NotImplementedError("get_infer_target must be implemented by subclasses")
@@ -106,9 +126,7 @@ class BaseAction(ABC):
         self.shared_context = shared_context
 
     def get_option(self, option_name: str, default: Any = None) -> Any:
-        """
+        """Resolve an option from the OptionsManager if present, else default."""
-        Resolve an option from the OptionsManager if present, otherwise use the fallback.
-        """
         if self.options_manager:
             return self.options_manager.get(option_name, default)
         return default
@@ -122,13 +140,22 @@ class BaseAction(ABC):
 
     @property
     def never_prompt(self) -> bool:
-        return self.get_option("never_prompt", self._never_prompt)
+        if self._never_prompt is not None:
+            return self._never_prompt
+        return self.get_option("never_prompt", False)
+
+    @property
+    def spinner_manager(self):
+        """Shortcut to access SpinnerManager via the OptionsManager."""
+        if not self.options_manager:
+            raise RuntimeError("SpinnerManager is not available (no OptionsManager set).")
+        return self.options_manager.spinners
 
     def prepare(
         self, shared_context: SharedContext, options_manager: OptionsManager | None = None
     ) -> BaseAction:
-        """
+        """Prepare the action specifically for sequential (ChainedAction) execution.
-        Prepare the action specifically for sequential (ChainedAction) execution.
+
         Can be overridden for chain-specific logic.
         """
         self.set_shared_context(shared_context)

falyx/action/chained_action.py

@@ -1,5 +1,68 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""chained_action.py"""
+"""Defines `ChainedAction`, a core Falyx construct for executing a sequence of actions
+in strict order, optionally injecting results from previous steps into subsequent ones.
+
+`ChainedAction` is designed for linear workflows where each step may depend on
+the output of the previous one. It supports rollback semantics, fallback recovery,
+and advanced error handling using `SharedContext`. Literal values are supported via
+automatic wrapping with `LiteralInputAction`.
+
+Key Features:
+- Executes a list of actions sequentially
+- Optional `auto_inject` to forward `last_result` into each step
+- Supports fallback recovery using `FallbackAction` when an error occurs
+- Rollback stack to undo already-completed actions on failure
+- Integrates with the full Falyx hook lifecycle
+- Previews and introspects workflow structure via `Rich`
+
+Use Cases:
+- Ordered pipelines (e.g., build → test → deploy)
+- Data transformations or ETL workflows
+- Linear decision trees or interactive wizards
+
+Special Behaviors:
+- Literal inputs (e.g., strings, numbers) are converted to `LiteralInputAction`
+- If an action raises and is followed by a `FallbackAction`, it will be skipped and recovered
+- If a `BreakChainSignal` is raised, the chain stops early and rollbacks are triggered
+
+Raises:
+- `EmptyChainError`: If no actions are present
+- `BreakChainSignal`: When explicitly triggered by a child action
+- `Exception`: For all unhandled failures during chained execution
+
+Example:
+    ChainedAction(
+        name="DeployFlow",
+        actions=[
+            ActionGroup(
+                name="PreDeploymentChecks",
+                actions=[
+                    Action(
+                        name="ValidateInputs",
+                        action=validate_inputs,
+                    ),
+                    Action(
+                        name="CheckDependencies",
+                        action=check_dependencies,
+                    ),
+                ],
+            ),
+            Action(
+                name="BuildArtifact",
+                action=build_artifact,
+            ),
+            Action(
+                name="Upload",
+                action=upload,
+            ),
+            Action(
+                name="NotifySuccess",
+                action=notify_success,
+            ),
+        ],
+        auto_inject=True,
+    )
+"""
 from __future__ import annotations
 
 from typing import Any, Awaitable, Callable, Sequence
@@ -22,8 +85,7 @@ from falyx.themes import OneColors
 
 
 class ChainedAction(BaseAction, ActionListMixin):
-    """
+    """ChainedAction executes a sequence of actions one after another.
-    ChainedAction executes a sequence of actions one after another.
 
     Features:
     - Supports optional automatic last_result injection (auto_inject).
@@ -35,8 +97,10 @@ class ChainedAction(BaseAction, ActionListMixin):
     previous results.
 
     Args:
-        name (str): Name of the chain.
+        name (str): Name of the chain. Used for logging and debugging.
         actions (list): List of actions or literals to execute.
+        args (tuple, optional): Positional arguments.
+        kwargs (dict, optional): Keyword arguments.
         hooks (HookManager, optional): Hooks for lifecycle events.
         inject_last_result (bool, optional): Whether to inject last results into kwargs
                                              by default.
@@ -51,6 +115,7 @@ class ChainedAction(BaseAction, ActionListMixin):
         name: str,
         actions: (
             Sequence[BaseAction | Callable[..., Any] | Callable[..., Awaitable[Any]]]
+            | Any
             | None
         ) = None,
         *,
@@ -61,12 +126,26 @@ class ChainedAction(BaseAction, ActionListMixin):
         inject_into: str = "last_result",
         auto_inject: bool = False,
         return_list: bool = False,
+        never_prompt: bool | None = None,
+        logging_hooks: bool = False,
+        spinner: bool = False,
+        spinner_message: str = "Processing...",
+        spinner_type: str = "dots",
+        spinner_style: str = OneColors.CYAN,
+        spinner_speed: float = 1.0,
     ) -> None:
         super().__init__(
             name,
             hooks=hooks,
             inject_last_result=inject_last_result,
             inject_into=inject_into,
+            never_prompt=never_prompt,
+            logging_hooks=logging_hooks,
+            spinner=spinner,
+            spinner_message=spinner_message,
+            spinner_type=spinner_type,
+            spinner_style=spinner_style,
+            spinner_speed=spinner_speed,
         )
         ActionListMixin.__init__(self)
         self.args = args
@@ -196,8 +275,7 @@ class ChainedAction(BaseAction, ActionListMixin):
     async def _rollback(
         self, rollback_stack: list[tuple[Action, tuple[Any, ...], dict[str, Any]]]
     ):
-        """
+        """Roll back all executed actions in reverse order.
-        Roll back all executed actions in reverse order.
 
         Rollbacks run even if a fallback recovered from failure,
         ensuring consistent undo of all side effects.
@@ -235,7 +313,8 @@ class ChainedAction(BaseAction, ActionListMixin):
 
     def __str__(self):
         return (
-            f"ChainedAction(name={self.name!r}, "
+            f"ChainedAction(name={self.name}, "
-            f"actions={[a.name for a in self.actions]!r}, "
+            f"actions={[a.name for a in self.actions]}, "
+            f"args={self.args!r}, kwargs={self.kwargs!r}, "
             f"auto_inject={self.auto_inject}, return_list={self.return_list})"
         )

falyx/action/confirm_action.py

@@ -1,3 +1,42 @@
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
+"""Defines `ConfirmAction`, a Falyx Action that prompts the user for confirmation
+before continuing execution.
+
+`ConfirmAction` supports a wide range of confirmation strategies, including:
+- Yes/No-style prompts
+- OK/Cancel dialogs
+- Typed confirmation (e.g., "CONFIRM" or "DELETE")
+- Acknowledge-only flows
+
+It is useful for adding safety gates, user-driven approval steps, or destructive
+operation guards in CLI workflows. This Action supports both interactive use and
+non-interactive (headless) behavior via `never_prompt`, as well as full hook lifecycle
+integration and optional result passthrough.
+
+Key Features:
+- Supports all common confirmation types (see `ConfirmType`)
+- Integrates with `PromptSession` for prompt_toolkit-based UX
+- Configurable fallback word validation and behavior on cancel
+- Can return the injected `last_result` instead of a boolean
+- Fully compatible with Falyx hooks, preview, and result injection
+
+Use Cases:
+- Safety checks before deleting, pushing, or overwriting resources
+- Gatekeeping interactive workflows
+- Validating irreversible or sensitive operations
+
+Example:
+    ConfirmAction(
+        name="ConfirmDeploy",
+        message="Are you sure you want to deploy to production?",
+        confirm_type="yes_no_cancel",
+    )
+
+Raises:
+- `CancelSignal`: When the user chooses to abort the action
+- `ValueError`: If an invalid `confirm_type` is provided
+"""
+
 from __future__ import annotations
 
 from typing import Any
@@ -11,15 +50,18 @@ from falyx.context import ExecutionContext
 from falyx.execution_registry import ExecutionRegistry as er
 from falyx.hook_manager import HookType
 from falyx.logger import logger
-from falyx.prompt_utils import confirm_async, should_prompt_user
+from falyx.prompt_utils import (
+    confirm_async,
+    rich_text_to_prompt_text,
+    should_prompt_user,
+)
 from falyx.signals import CancelSignal
 from falyx.themes import OneColors
 from falyx.validators import word_validator, words_validator
 
 
 class ConfirmAction(BaseAction):
-    """
+    """Action to confirm an operation with the user.
-    Action to confirm an operation with the user.
 
     There are several ways to confirm an action, such as using a simple
     yes/no prompt. You can also use a confirmation type that requires the user
@@ -30,8 +72,8 @@ class ConfirmAction(BaseAction):
     with an operation.
 
     Attributes:
-        name (str): Name of the action.
+        name (str): Name of the action. Used for logging and debugging.
-        message (str): The confirmation message to display.
+        prompt_message (str): The confirmation message to display.
         confirm_type (ConfirmType | str): The type of confirmation to use.
             Options include YES_NO, YES_CANCEL, YES_NO_CANCEL, TYPE_WORD, and OK_CANCEL.
         prompt_session (PromptSession | None): The session to use for input.
@@ -44,7 +86,7 @@ class ConfirmAction(BaseAction):
     def __init__(
         self,
         name: str,
-        message: str = "Confirm?",
+        prompt_message: str = "Confirm?",
         confirm_type: ConfirmType | str = ConfirmType.YES_NO,
         prompt_session: PromptSession | None = None,
         never_prompt: bool = False,
@@ -53,8 +95,7 @@ class ConfirmAction(BaseAction):
         inject_last_result: bool = True,
         inject_into: str = "last_result",
     ):
-        """
+        """Initialize the ConfirmAction.
-        Initialize the ConfirmAction.
 
         Args:
             message (str): The confirmation message to display.
@@ -71,34 +112,34 @@ class ConfirmAction(BaseAction):
             inject_into=inject_into,
             never_prompt=never_prompt,
         )
-        self.message = message
+        self.prompt_message = prompt_message
-        self.confirm_type = self._coerce_confirm_type(confirm_type)
+        self.confirm_type = ConfirmType(confirm_type)
-        self.prompt_session = prompt_session or PromptSession()
+        self.prompt_session = prompt_session or PromptSession(
+            interrupt_exception=CancelSignal
+        )
         self.word = word
         self.return_last_result = return_last_result
 
-    def _coerce_confirm_type(self, confirm_type: ConfirmType | str) -> ConfirmType:
-        """Coerce the confirm_type to a ConfirmType enum."""
-        if isinstance(confirm_type, ConfirmType):
-            return confirm_type
-        elif isinstance(confirm_type, str):
-            return ConfirmType(confirm_type)
-        return ConfirmType(confirm_type)
-
     async def _confirm(self) -> bool:
         """Confirm the action with the user."""
         match self.confirm_type:
             case ConfirmType.YES_NO:
                 return await confirm_async(
-                    self.message,
+                    rich_text_to_prompt_text(self.prompt_message),
-                    prefix="❓ ",
+                    suffix=rich_text_to_prompt_text(
-                    suffix=" [Y/n] > ",
+                        f" [[{OneColors.GREEN_b}]Y[/]]es, "
+                        f"[[{OneColors.DARK_RED_b}]N[/]]o > "
+                    ),
                     session=self.prompt_session,
                 )
             case ConfirmType.YES_NO_CANCEL:
                 error_message = "Enter 'Y', 'y' to confirm, 'N', 'n' to decline, or 'C', 'c' to abort."
                 answer = await self.prompt_session.prompt_async(
-                    f"❓ {self.message} [Y]es, [N]o, or [C]ancel to abort > ",
+                    rich_text_to_prompt_text(
+                        f"❓ {self.prompt_message} [[{OneColors.GREEN_b}]Y[/]]es, "
+                        f"[[{OneColors.DARK_YELLOW_b}]N[/]]o, "
+                        f"or [[{OneColors.DARK_RED_b}]C[/]]ancel to abort > "
+                    ),
                     validator=words_validator(
                         ["Y", "N", "C"], error_message=error_message
                     ),
@@ -108,13 +149,19 @@ class ConfirmAction(BaseAction):
                 return answer.upper() == "Y"
             case ConfirmType.TYPE_WORD:
                 answer = await self.prompt_session.prompt_async(
-                    f"❓ {self.message} [{self.word}] to confirm or [N/n] > ",
+                    rich_text_to_prompt_text(
+                        f"❓ {self.prompt_message} [[{OneColors.GREEN_b}]{self.word.upper()}[/]] "
+                        f"to confirm or [[{OneColors.DARK_RED}]N[/{OneColors.DARK_RED}]] > "
+                    ),
                     validator=word_validator(self.word),
                 )
                 return answer.upper().strip() != "N"
             case ConfirmType.TYPE_WORD_CANCEL:
                 answer = await self.prompt_session.prompt_async(
-                    f"❓ {self.message} [{self.word}] to confirm or [N/n] > ",
+                    rich_text_to_prompt_text(
+                        f"❓ {self.prompt_message} [[{OneColors.GREEN_b}]{self.word.upper()}[/]] "
+                        f"to confirm or [[{OneColors.DARK_RED}]N[/{OneColors.DARK_RED}]] > "
+                    ),
                     validator=word_validator(self.word),
                 )
                 if answer.upper().strip() == "N":
@@ -122,9 +169,11 @@ class ConfirmAction(BaseAction):
                 return answer.upper().strip() == self.word.upper().strip()
             case ConfirmType.YES_CANCEL:
                 answer = await confirm_async(
-                    self.message,
+                    rich_text_to_prompt_text(self.prompt_message),
-                    prefix="❓ ",
+                    suffix=rich_text_to_prompt_text(
-                    suffix=" [Y/n] > ",
+                        f" [[{OneColors.GREEN_b}]Y[/]]es, "
+                        f"[[{OneColors.DARK_RED_b}]N[/]]o > "
+                    ),
                     session=self.prompt_session,
                 )
                 if not answer:
@@ -133,7 +182,10 @@ class ConfirmAction(BaseAction):
             case ConfirmType.OK_CANCEL:
                 error_message = "Enter 'O', 'o' to confirm or 'C', 'c' to abort."
                 answer = await self.prompt_session.prompt_async(
-                    f"❓ {self.message} [O]k to confirm, [C]ancel to abort > ",
+                    rich_text_to_prompt_text(
+                        f"❓ {self.prompt_message} [[{OneColors.GREEN_b}]O[/]]k to confirm, "
+                        f"[[{OneColors.DARK_RED}]C[/]]ancel to abort > "
+                    ),
                     validator=words_validator(["O", "C"], error_message=error_message),
                 )
                 if answer.upper() == "C":
@@ -141,7 +193,9 @@ class ConfirmAction(BaseAction):
                 return answer.upper() == "O"
             case ConfirmType.ACKNOWLEDGE:
                 answer = await self.prompt_session.prompt_async(
-                    f"❓ {self.message} [A]cknowledge > ",
+                    rich_text_to_prompt_text(
+                        f"❓ {self.prompt_message} [[{OneColors.CYAN_b}]A[/]]cknowledge > "
+                    ),
                     validator=word_validator("A"),
                 )
                 return answer.upper().strip() == "A"
@@ -200,7 +254,7 @@ class ConfirmAction(BaseAction):
             if not parent
             else parent.add(f"[{OneColors.CYAN_b}]ConfirmAction[/]: {self.name}")
         )
-        tree.add(f"[bold]Message:[/] {self.message}")
+        tree.add(f"[bold]Message:[/] {self.prompt_message}")
         tree.add(f"[bold]Type:[/] {self.confirm_type.value}")
         tree.add(f"[bold]Prompt Required:[/] {'No' if self.never_prompt else 'Yes'}")
         if self.confirm_type in (ConfirmType.TYPE_WORD, ConfirmType.TYPE_WORD_CANCEL):
@@ -210,6 +264,6 @@ class ConfirmAction(BaseAction):
 
     def __str__(self) -> str:
         return (
-            f"ConfirmAction(name={self.name}, message={self.message}, "
+            f"ConfirmAction(name={self.name}, message={self.prompt_message}, "
             f"confirm_type={self.confirm_type}, return_last_result={self.return_last_result})"
         )

falyx/action/fallback_action.py

@@ -1,5 +1,40 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""fallback_action.py"""
+"""Defines `FallbackAction`, a lightweight recovery Action used within `ChainedAction`
+pipelines to gracefully handle errors or missing results from a preceding step.
+
+When placed immediately after a failing or null-returning Action, `FallbackAction`
+injects the `last_result` and checks whether it is `None`. If so, it substitutes a
+predefined fallback value and allows the chain to continue. If `last_result` is valid,
+it is passed through unchanged.
+
+This mechanism allows workflows to recover from failure or gaps in data
+without prematurely terminating the entire chain.
+
+Key Features:
+- Injects and inspects `last_result`
+- Replaces `None` with a fallback value
+- Consumes upstream errors when used with `ChainedAction`
+- Fully compatible with Falyx's preview and hook systems
+
+Typical Use Cases:
+- Graceful degradation in chained workflows
+- Providing default values when earlier steps are optional
+- Replacing missing data with static or precomputed values
+
+Example:
+    ChainedAction(
+        name="FetchWithFallback",
+        actions=[
+            Action("MaybeFetchRemoteAction", action=fetch_data),
+            FallbackAction(fallback={"data": "default"}),
+            Action("ProcessDataAction", action=process_data),
+        ],
+        auto_inject=True,
+    )
+
+The `FallbackAction` ensures that even if `MaybeFetchRemoteAction` fails or returns
+None, `ProcessDataAction` still receives a usable input.
+"""
 from functools import cached_property
 from typing import Any
 
@@ -10,8 +45,7 @@ from falyx.themes import OneColors
 
 
 class FallbackAction(Action):
-    """
+    """FallbackAction provides a default value if the previous action failed or
-    FallbackAction provides a default value if the previous action failed or
     returned None.
 
     It injects the last result and checks:

falyx/action/http_action.py

@@ -1,6 +1,5 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""http_action.py
+"""Defines `HTTPAction` for making HTTP requests using aiohttp.
-Defines an Action subclass for making HTTP requests using aiohttp within Falyx workflows.
 
 Features:
 - Automatic reuse of aiohttp.ClientSession via SharedContext
@@ -32,8 +31,7 @@ async def close_shared_http_session(context: ExecutionContext) -> None:
 
 
 class HTTPAction(Action):
-    """
+    """An Action for executing HTTP requests using aiohttp with shared session reuse.
-    An Action for executing HTTP requests using aiohttp with shared session reuse.
 
     This action integrates seamlessly into Falyx pipelines, with automatic session
     management, result injection, and lifecycle hook support. It is ideal for CLI-driven
@@ -47,7 +45,7 @@ class HTTPAction(Action):
     - Retry and result injection compatible
 
     Args:
-        name (str): Name of the action.
+        name (str): Name of the action. Used for logging and debugging.
         method (str): HTTP method (e.g., 'GET', 'POST').
         url (str): The request URL.
         headers (dict[str, str], optional): Request headers.
@@ -77,6 +75,11 @@ class HTTPAction(Action):
         inject_into: str = "last_result",
         retry: bool = False,
         retry_policy=None,
+        spinner: bool = False,
+        spinner_message: str = "Processing...",
+        spinner_type: str = "dots",
+        spinner_style: str = OneColors.CYAN,
+        spinner_speed: float = 1.0,
     ):
         self.method = method.upper()
         self.url = url
@@ -95,6 +98,11 @@ class HTTPAction(Action):
             inject_into=inject_into,
             retry=retry,
             retry_policy=retry_policy,
+            spinner=spinner,
+            spinner_message=spinner_message,
+            spinner_type=spinner_type,
+            spinner_style=spinner_style,
+            spinner_speed=spinner_speed,
         )
 
     async def _request(self, *_, **__) -> dict[str, Any]:

falyx/action/io_action.py

@@ -1,6 +1,5 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""io_action.py
+"""BaseIOAction: A base class for stream- or buffer-based IO-driven Actions.
-BaseIOAction: A base class for stream- or buffer-based IO-driven Actions.
 
 This module defines `BaseIOAction`, a specialized variant of `BaseAction`
 that interacts with standard input and output, enabling command-line pipelines,
@@ -29,8 +28,7 @@ from falyx.themes import OneColors
 
 
 class BaseIOAction(BaseAction):
-    """
+    """Base class for IO-driven Actions that operate on stdin/stdout input streams.
-    Base class for IO-driven Actions that operate on stdin/stdout input streams.
 
     Designed for use in shell pipelines or programmatic workflows that pass data
     through chained commands. It handles reading input, transforming it, and
@@ -48,8 +46,11 @@ class BaseIOAction(BaseAction):
     - `to_output(data)`: Convert result into output string or bytes.
     - `_run(parsed_input, *args, **kwargs)`: Core execution logic.
 
-    Attributes:
+    Args:
+        name (str): Name of the action. Used for logging and debugging.
+        hooks (HookManager | None): Hook manager for lifecycle events.
         mode (str): Either "buffered" or "stream". Controls input behavior.
+        logging_hooks (bool): Whether to register debug hooks for logging.
         inject_last_result (bool): Whether to inject shared context input.
     """
 

falyx/action/literal_input_action.py

@@ -1,5 +1,35 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""literal_input_action.py"""
+"""Defines `LiteralInputAction`, a lightweight Falyx Action that injects a static,
+predefined value into a `ChainedAction` workflow.
+
+This Action is useful for embedding literal values (e.g., strings, numbers,
+dicts) as part of a CLI pipeline without writing custom callables. It behaves
+like a constant-returning function that can serve as the starting point,
+fallback, or manual override within a sequence of actions.
+
+Key Features:
+- Wraps any static value as a Falyx-compatible Action
+- Fully hookable and previewable like any other Action
+- Enables declarative workflows with no required user input
+- Compatible with auto-injection and shared context in `ChainedAction`
+
+Common Use Cases:
+- Supplying default parameters or configuration values mid-pipeline
+- Starting a chain with a fixed value (e.g., base URL, credentials)
+- Bridging gaps between conditional or dynamically generated Actions
+
+Example:
+    ChainedAction(
+        name="SendStaticMessage",
+        actions=[
+            LiteralInputAction("hello world"),
+            SendMessageAction(),
+        ]
+    )
+
+The `LiteralInputAction` is a foundational building block for pipelines that
+require predictable, declarative value injection at any stage.
+"""
 from __future__ import annotations
 
 from functools import cached_property
@@ -12,8 +42,7 @@ from falyx.themes import OneColors
 
 
 class LiteralInputAction(Action):
-    """
+    """LiteralInputAction injects a static value into a ChainedAction.
-    LiteralInputAction injects a static value into a ChainedAction.
 
     This allows embedding hardcoded values mid-pipeline, useful when:
     - Providing default or fallback inputs.

falyx/action/load_file_action.py

@@ -1,5 +1,40 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""load_file_action.py"""
+"""Defines `LoadFileAction`, a Falyx Action for reading and parsing the contents of a
+file at runtime in a structured, introspectable, and lifecycle-aware manner.
+
+This action supports multiple common file types—including plain text, structured data
+formats (JSON, YAML, TOML), tabular formats (CSV, TSV), XML, and raw Path objects—
+making it ideal for configuration loading, data ingestion, and file-driven workflows.
+
+It integrates seamlessly with Falyx pipelines and supports `last_result` injection,
+Rich-powered previews, and lifecycle hook execution.
+
+Key Features:
+- Format-aware parsing for structured and unstructured files
+- Supports injection of `last_result` as the target file path
+- Headless-compatible via `never_prompt` and argument overrides
+- Lifecycle hooks: before, success, error, after, teardown
+- Preview renders file metadata, size, modified timestamp, and parsed content
+- Fully typed and alias-compatible via `FileType`
+
+Supported File Types:
+- `TEXT`: Raw text string (UTF-8)
+- `PATH`: The file path itself as a `Path` object
+- `JSON`, `YAML`, `TOML`: Parsed into `dict` or `list`
+- `CSV`, `TSV`: Parsed into `list[list[str]]`
+- `XML`: Returns the root `ElementTree.Element`
+
+Example:
+    LoadFileAction(
+        name="LoadSettings",
+        file_path="config/settings.yaml",
+        file_type="yaml"
+    )
+
+This module is a foundational building block for file-driven CLI workflows in Falyx.
+It is often paired with `SaveFileAction`, `SelectionAction`, or `ConfirmAction` for
+robust and interactive pipelines.
+"""
 import csv
 import json
 import xml.etree.ElementTree as ET
@@ -21,13 +56,57 @@ from falyx.themes import OneColors
 
 
 class LoadFileAction(BaseAction):
-    """LoadFileAction allows loading and parsing files of various types."""
+    """LoadFileAction loads and parses the contents of a file at runtime.
+
+    This action supports multiple common file formats—including plain text, JSON,
+    YAML, TOML, XML, CSV, and TSV—and returns a parsed representation of the file.
+    It can be used to inject external data into a CLI workflow, load configuration files,
+    or process structured datasets interactively or in headless mode.
+
+    Key Features:
+    - Supports rich previewing of file metadata and contents
+    - Auto-injects `last_result` as `file_path` if configured
+    - Hookable at every lifecycle stage (before, success, error, after, teardown)
+    - Supports both static and dynamic file targets (via args or injected values)
+
+    Args:
+        name (str): Name of the action for tracking and logging.
+        file_path (str | Path | None): Path to the file to be loaded. Can be passed
+            directly or injected via `last_result`.
+        file_type (FileType | str): Type of file to parse. Options include:
+            TEXT, JSON, YAML, TOML, CSV, TSV, XML, PATH.
+        encoding (str): Encoding to use when reading files (default: 'UTF-8').
+        inject_last_result (bool): Whether to use the last result as the file path.
+        inject_into (str): Name of the kwarg to inject `last_result` into (default: 'file_path').
+
+    Returns:
+        Any: The parsed file content. Format depends on `file_type`:
+            - TEXT: str
+            - JSON/YAML/TOML: dict or list
+            - CSV/TSV: list[list[str]]
+            - XML: xml.etree.ElementTree
+            - PATH: Path object
+
+    Raises:
+        ValueError: If `file_path` is missing or invalid.
+        FileNotFoundError: If the file does not exist.
+        TypeError: If `file_type` is unsupported or the factory does not return a BaseAction.
+        Any parsing errors will be logged but not raised unless fatal.
+
+    Example:
+        LoadFileAction(
+            name="LoadConfig",
+            file_path="config/settings.yaml",
+            file_type="yaml"
+        )
+    """
 
     def __init__(
         self,
         name: str,
         file_path: str | Path | None = None,
         file_type: FileType | str = FileType.TEXT,
+        encoding: str = "UTF-8",
         inject_last_result: bool = False,
         inject_into: str = "file_path",
     ):
@@ -35,7 +114,8 @@ class LoadFileAction(BaseAction):
             name=name, inject_last_result=inject_last_result, inject_into=inject_into
         )
         self._file_path = self._coerce_file_path(file_path)
-        self._file_type = self._coerce_file_type(file_type)
+        self._file_type = FileType(file_type)
+        self.encoding = encoding
 
     @property
     def file_path(self) -> Path | None:
@@ -63,20 +143,6 @@ class LoadFileAction(BaseAction):
         """Get the file type."""
         return self._file_type
 
-    @file_type.setter
-    def file_type(self, value: FileType | str):
-        """Set the file type, converting to FileType if necessary."""
-        self._file_type = self._coerce_file_type(value)
-
-    def _coerce_file_type(self, file_type: FileType | str) -> FileType:
-        """Coerce the file type to a FileType enum."""
-        if isinstance(file_type, FileType):
-            return file_type
-        elif isinstance(file_type, str):
-            return FileType(file_type)
-        else:
-            raise TypeError("file_type must be a FileType enum or string")
-
     def get_infer_target(self) -> tuple[None, None]:
         return None, None
 
@@ -91,32 +157,35 @@ class LoadFileAction(BaseAction):
         value: Any = None
         try:
             if self.file_type == FileType.TEXT:
-                value = self.file_path.read_text(encoding="UTF-8")
+                value = self.file_path.read_text(encoding=self.encoding)
             elif self.file_type == FileType.PATH:
                 value = self.file_path
             elif self.file_type == FileType.JSON:
-                value = json.loads(self.file_path.read_text(encoding="UTF-8"))
+                value = json.loads(self.file_path.read_text(encoding=self.encoding))
             elif self.file_type == FileType.TOML:
-                value = toml.loads(self.file_path.read_text(encoding="UTF-8"))
+                value = toml.loads(self.file_path.read_text(encoding=self.encoding))
             elif self.file_type == FileType.YAML:
-                value = yaml.safe_load(self.file_path.read_text(encoding="UTF-8"))
+                value = yaml.safe_load(self.file_path.read_text(encoding=self.encoding))
             elif self.file_type == FileType.CSV:
-                with open(self.file_path, newline="", encoding="UTF-8") as csvfile:
+                with open(self.file_path, newline="", encoding=self.encoding) as csvfile:
                     reader = csv.reader(csvfile)
                     value = list(reader)
             elif self.file_type == FileType.TSV:
-                with open(self.file_path, newline="", encoding="UTF-8") as tsvfile:
+                with open(self.file_path, newline="", encoding=self.encoding) as tsvfile:
                     reader = csv.reader(tsvfile, delimiter="\t")
                     value = list(reader)
             elif self.file_type == FileType.XML:
-                tree = ET.parse(self.file_path, parser=ET.XMLParser(encoding="UTF-8"))
+                tree = ET.parse(
+                    self.file_path, parser=ET.XMLParser(encoding=self.encoding)
+                )
                 root = tree.getroot()
-                value = ET.tostring(root, encoding="unicode")
+                value = root
             else:
                 raise ValueError(f"Unsupported return type: {self.file_type}")
 
         except Exception as error:
             logger.error("Failed to parse %s: %s", self.file_path.name, error)
+            raise
         return value
 
     async def _run(self, *args, **kwargs) -> Any:
@@ -173,7 +242,7 @@ class LoadFileAction(BaseAction):
                     for line in preview_lines:
                         content_tree.add(f"[dim]{line}[/]")
                 elif self.file_type in {FileType.JSON, FileType.YAML, FileType.TOML}:
-                    raw = self.load_file()
+                    raw = await self.load_file()
                     if raw is not None:
                         preview_str = (
                             json.dumps(raw, indent=2)

falyx/action/menu_action.py

@@ -1,5 +1,41 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""menu_action.py"""
+"""Defines `MenuAction`, a one-shot, interactive menu-style Falyx Action that presents
+a set of labeled options to the user and executes the corresponding action based on
+their selection.
+
+Unlike the persistent top-level Falyx menu, `MenuAction` is intended for embedded,
+self-contained decision points within a workflow. It supports both interactive and
+non-interactive (headless) usage, integrates fully with the Falyx hook lifecycle,
+and allows optional defaulting or input injection from previous actions.
+
+Each selectable item is defined in a `MenuOptionMap`, mapping a single-character or
+keyword to a `MenuOption`, which includes a description and a corresponding `BaseAction`.
+
+Key Features:
+- Renders a Rich-powered multi-column menu table
+- Accepts custom prompt sessions or tables
+- Supports `last_result` injection for context-aware defaults
+- Gracefully handles `BackSignal` and `QuitSignal` for flow control
+- Compatible with preview trees and introspection tools
+
+Use Cases:
+- In-workflow submenus or branches
+- Interactive control points in chained or grouped workflows
+- Configurable menus for multi-step user-driven automation
+
+Example:
+    MenuAction(
+        name="SelectEnv",
+        menu_options=MenuOptionMap(options={
+            "D": MenuOption("Deploy to Dev", DeployDevAction()),
+            "P": MenuOption("Deploy to Prod", DeployProdAction()),
+        }),
+        default_selection="D",
+    )
+
+This module is ideal for enabling structured, discoverable, and declarative
+menus in both interactive and programmatic CLI automation.
+"""
 from typing import Any
 
 from prompt_toolkit import PromptSession
@@ -12,14 +48,64 @@ from falyx.execution_registry import ExecutionRegistry as er
 from falyx.hook_manager import HookType
 from falyx.logger import logger
 from falyx.menu import MenuOptionMap
+from falyx.prompt_utils import rich_text_to_prompt_text
 from falyx.selection import prompt_for_selection, render_table_base
-from falyx.signals import BackSignal, QuitSignal
+from falyx.signals import BackSignal, CancelSignal, QuitSignal
 from falyx.themes import OneColors
 from falyx.utils import chunks
 
 
 class MenuAction(BaseAction):
-    """MenuAction class for creating single use menu actions."""
+    """MenuAction displays a one-time interactive menu of predefined options,
+    each mapped to a corresponding Action.
+
+    Unlike the main Falyx menu system, `MenuAction` is intended for scoped,
+    self-contained selection logic—ideal for small in-flow menus, decision branches,
+    or embedded control points in larger workflows.
+
+    Each selectable item is defined in a `MenuOptionMap`, which maps a string key
+    to a `MenuOption`, bundling a description and a callable Action.
+
+    Key Features:
+    - One-shot selection from labeled actions
+    - Optional default or last_result-based selection
+    - Full hook lifecycle (before, success, error, after, teardown)
+    - Works with or without rendering a table (for headless use)
+    - Compatible with `BackSignal` and `QuitSignal` for graceful control flow exits
+
+    Args:
+        name (str): Name of the action. Used for logging and debugging.
+        menu_options (MenuOptionMap): Mapping of keys to `MenuOption` objects.
+        title (str): Table title displayed when prompting the user.
+        columns (int): Number of columns in the rendered table.
+        prompt_message (str): Prompt text displayed before selection.
+        default_selection (str): Key to use if no user input is provided.
+        inject_last_result (bool): Whether to inject `last_result` into args/kwargs.
+        inject_into (str): Key under which to inject `last_result`.
+        prompt_session (PromptSession | None): Custom session for Prompt Toolkit input.
+        never_prompt (bool): If True, skips interaction and uses default or last_result.
+        include_reserved (bool): Whether to include reserved keys (like 'X' for Exit).
+        show_table (bool): Whether to render the Rich menu table.
+        custom_table (Table | None): Pre-rendered Rich Table (bypasses auto-building).
+
+    Returns:
+        Any: The result of the selected option's Action.
+
+    Raises:
+        BackSignal: When the user chooses to return to a previous menu.
+        QuitSignal: When the user chooses to exit the program.
+        ValueError: If `never_prompt=True` but no default selection is resolvable.
+        Exception: Any error raised during the execution of the selected Action.
+
+    Example:
+        MenuAction(
+            name="ChooseBranch",
+            menu_options=MenuOptionMap(options={
+                "A": MenuOption("Run analysis", ActionGroup(...)),
+                "B": MenuOption("Run report", Action(...)),
+            }),
+        )
+    """
 
     def __init__(
         self,
@@ -47,9 +133,11 @@ class MenuAction(BaseAction):
         self.menu_options = menu_options
         self.title = title
         self.columns = columns
-        self.prompt_message = prompt_message
+        self.prompt_message = rich_text_to_prompt_text(prompt_message)
         self.default_selection = default_selection
-        self.prompt_session = prompt_session or PromptSession()
+        self.prompt_session = prompt_session or PromptSession(
+            interrupt_exception=CancelSignal
+        )
         self.include_reserved = include_reserved
         self.show_table = show_table
         self.custom_table = custom_table

falyx/action/process_action.py

@@ -1,5 +1,41 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""process_action.py"""
+"""Defines `ProcessAction`, a Falyx Action that executes a blocking or CPU-bound function
+in a separate process using `concurrent.futures.ProcessPoolExecutor`.
+
+This is useful for offloading expensive computations or subprocess-compatible operations
+from the main event loop, while maintaining Falyx's composable, hookable, and injectable
+execution model.
+
+`ProcessAction` mirrors the behavior of a normal `Action`, but ensures isolation from
+the asyncio event loop and handles serialization (pickling) of arguments and injected
+state.
+
+Key Features:
+- Runs a callable in a separate Python process
+- Compatible with `last_result` injection for chained workflows
+- Validates that injected values are pickleable before dispatch
+- Supports hook lifecycle (`before`, `on_success`, `on_error`, etc.)
+- Custom executor support for reuse or configuration
+
+Use Cases:
+- CPU-intensive operations (e.g., image processing, simulations, data transformations)
+- Blocking third-party libraries that don't cooperate with asyncio
+- CLI workflows that require subprocess-level parallelism or safety
+
+Example:
+    ProcessAction(
+        name="ComputeChecksum",
+        action=calculate_sha256,
+        args=("large_file.bin",),
+    )
+
+Raises:
+- `ValueError`: If an injected value is not pickleable
+- `Exception`: Propagated from the subprocess on failure
+
+This module enables structured offloading of workload in CLI pipelines while maintaining
+full introspection and lifecycle management.
+"""
 from __future__ import annotations
 
 import asyncio
@@ -17,8 +53,7 @@ from falyx.themes import OneColors
 
 
 class ProcessAction(BaseAction):
-    """
+    """ProcessAction runs a function in a separate process using ProcessPoolExecutor.
-    ProcessAction runs a function in a separate process using ProcessPoolExecutor.
 
     Features:
     - Executes CPU-bound or blocking tasks without blocking the main event loop.
@@ -47,12 +82,26 @@ class ProcessAction(BaseAction):
         executor: ProcessPoolExecutor | None = None,
         inject_last_result: bool = False,
         inject_into: str = "last_result",
+        never_prompt: bool | None = None,
+        logging_hooks: bool = False,
+        spinner: bool = False,
+        spinner_message: str = "Processing...",
+        spinner_type: str = "dots",
+        spinner_style: str = OneColors.CYAN,
+        spinner_speed: float = 1.0,
     ):
         super().__init__(
             name,
             hooks=hooks,
             inject_last_result=inject_last_result,
             inject_into=inject_into,
+            never_prompt=never_prompt,
+            logging_hooks=logging_hooks,
+            spinner=spinner,
+            spinner_message=spinner_message,
+            spinner_type=spinner_type,
+            spinner_style=spinner_style,
+            spinner_speed=spinner_speed,
         )
         self.action = action
         self.args = args

falyx/action/process_pool_action.py

@@ -1,5 +1,18 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""process_pool_action.py"""
+"""Defines `ProcessPoolAction`, a parallelized action executor that distributes
+tasks across multiple processes using Python's `concurrent.futures.ProcessPoolExecutor`.
+
+This module enables structured execution of CPU-bound tasks in parallel while
+retaining Falyx's core guarantees: lifecycle hooks, error isolation, execution context
+tracking, and introspectable previews.
+
+Key Components:
+- ProcessTask: Lightweight wrapper for a task + args/kwargs
+- ProcessPoolAction: Parallel action that runs tasks concurrently in separate processes
+
+Use this module to accelerate workflows involving expensive computation or
+external resources that benefit from true parallelism.
+"""
 from __future__ import annotations
 
 import asyncio
@@ -23,6 +36,20 @@ from falyx.themes import OneColors
 
 @dataclass
 class ProcessTask:
+    """Represents a callable task with its arguments for parallel execution.
+
+    This lightweight container is used to queue individual tasks for execution
+    inside a `ProcessPoolAction`.
+
+    Attributes:
+        task (Callable): A function to execute.
+        args (tuple): Positional arguments to pass to the function.
+        kwargs (dict): Keyword arguments to pass to the function.
+
+    Raises:
+        TypeError: If `task` is not callable.
+    """
+
     task: Callable[..., Any]
     args: tuple = ()
     kwargs: dict[str, Any] = field(default_factory=dict)
@@ -33,7 +60,43 @@ class ProcessTask:
 
 
 class ProcessPoolAction(BaseAction):
-    """ """
+    """Executes a set of independent tasks in parallel using a process pool.
+
+    `ProcessPoolAction` is ideal for CPU-bound tasks that benefit from
+    concurrent execution in separate processes. Each task is wrapped in a
+    `ProcessTask` instance and executed in a `concurrent.futures.ProcessPoolExecutor`.
+
+    Key Features:
+    - Parallel, process-based execution
+    - Hook lifecycle support across all stages
+    - Supports argument injection (e.g., `last_result`)
+    - Compatible with retry behavior and shared context propagation
+    - Captures all task results (including exceptions) and records execution context
+
+    Args:
+        name (str): Name of the action. Used for logging and debugging.
+        actions (Sequence[ProcessTask] | None): A list of tasks to run.
+        hooks (HookManager | None): Optional hook manager for lifecycle events.
+        executor (ProcessPoolExecutor | None): Custom executor instance (optional).
+        inject_last_result (bool): Whether to inject the last result into task kwargs.
+        inject_into (str): Name of the kwarg to use for injected result.
+
+    Returns:
+        list[Any]: A list of task results in submission order. Exceptions are preserved.
+
+    Raises:
+        EmptyPoolError: If no actions are registered.
+        ValueError: If injected `last_result` is not pickleable.
+
+    Example:
+        ProcessPoolAction(
+            name="ParallelTransforms",
+            actions=[
+                ProcessTask(func_a, args=(1,)),
+                ProcessTask(func_b, kwargs={"x": 2}),
+            ]
+        )
+    """
 
     def __init__(
         self,
@@ -81,7 +144,7 @@ class ProcessPoolAction(BaseAction):
     async def _run(self, *args, **kwargs) -> Any:
         if not self.actions:
             raise EmptyPoolError(f"[{self.name}] No actions to execute.")
-        shared_context = SharedContext(name=self.name, action=self, is_parallel=True)
+        shared_context = SharedContext(name=self.name, action=self, is_concurrent=True)
         if self.shared_context:
             shared_context.set_shared_result(self.shared_context.last_result())
         if self.inject_last_result and self.shared_context:

falyx/action/prompt_menu_action.py

@@ -1,5 +1,15 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""prompt_menu_action.py"""
+"""Defines `PromptMenuAction`, a Falyx Action that prompts the user to choose from
+a list of labeled options using a single-line prompt input. Each option corresponds
+to a `MenuOption` that wraps a description and an executable action.
+
+Unlike `MenuAction`, this action renders a flat, inline prompt (e.g., `Option1 | Option2`)
+without using a rich table. It is ideal for compact decision points, hotkey-style menus,
+or contextual user input flows.
+
+Key Components:
+- PromptMenuAction: Inline prompt-driven menu runner
+"""
 from typing import Any
 
 from prompt_toolkit import PromptSession
@@ -12,12 +22,58 @@ from falyx.execution_registry import ExecutionRegistry as er
 from falyx.hook_manager import HookType
 from falyx.logger import logger
 from falyx.menu import MenuOptionMap
-from falyx.signals import BackSignal, QuitSignal
+from falyx.prompt_utils import rich_text_to_prompt_text
+from falyx.signals import BackSignal, CancelSignal, QuitSignal
 from falyx.themes import OneColors
 
 
 class PromptMenuAction(BaseAction):
-    """PromptMenuAction class for creating prompt -> actions."""
+    """Displays a single-line interactive prompt for selecting an option from a menu.
+
+    `PromptMenuAction` is a lightweight alternative to `MenuAction`, offering a more
+    compact selection interface. Instead of rendering a full table, it displays
+    available keys inline as a placeholder (e.g., `A | B | C`) and accepts the user's
+    input to execute the associated action.
+
+    Each key is defined in a `MenuOptionMap`, which maps to a `MenuOption` containing
+    a description and an executable action.
+
+    Key Features:
+    - Minimal UI: rendered as a single prompt line with placeholder
+    - Optional fallback to `default_selection` or injected `last_result`
+    - Fully hookable lifecycle (before, success, error, after, teardown)
+    - Supports reserved keys and structured error recovery
+
+    Args:
+        name (str): Name of the action. Used for logging and debugging.
+        menu_options (MenuOptionMap): A mapping of keys to `MenuOption` objects.
+        prompt_message (str): Text displayed before user input (default: "Select > ").
+        default_selection (str): Fallback key if no input is provided.
+        inject_last_result (bool): Whether to use `last_result` as a fallback input key.
+        inject_into (str): Kwarg name under which to inject the last result.
+        prompt_session (PromptSession | None): Custom Prompt Toolkit session.
+        never_prompt (bool): If True, skips user input and uses `default_selection`.
+        include_reserved (bool): Whether to include reserved keys in logic and preview.
+
+    Returns:
+        Any: The result of the selected option's action.
+
+    Raises:
+        BackSignal: If the user signals to return to the previous menu.
+        QuitSignal: If the user signals to exit the CLI entirely.
+        ValueError: If `never_prompt` is enabled but no fallback is available.
+        Exception: If an error occurs during the action's execution.
+
+    Example:
+        PromptMenuAction(
+            name="HotkeyPrompt",
+            menu_options=MenuOptionMap(options={
+                "R": MenuOption("Run", ChainedAction(...)),
+                "S": MenuOption("Skip", Action(...)),
+            }),
+            prompt_message="Choose action > ",
+        )
+    """
 
     def __init__(
         self,
@@ -39,9 +95,11 @@ class PromptMenuAction(BaseAction):
             never_prompt=never_prompt,
         )
         self.menu_options = menu_options
-        self.prompt_message = prompt_message
+        self.prompt_message = rich_text_to_prompt_text(prompt_message)
         self.default_selection = default_selection
-        self.prompt_session = prompt_session or PromptSession()
+        self.prompt_session = prompt_session or PromptSession(
+            interrupt_exception=CancelSignal
+        )
         self.include_reserved = include_reserved
 
     def get_infer_target(self) -> tuple[None, None]:

falyx/action/save_file_action.py

@@ -1,5 +1,24 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""save_file_action.py"""
+"""Defines `SaveFileAction`, a Falyx Action for writing structured or unstructured data
+to a file in a variety of supported formats.
+
+Supports overwrite control, automatic directory creation, and full lifecycle hook
+integration. Compatible with chaining and injection of upstream results via
+`inject_last_result`.
+
+Supported formats: TEXT, JSON, YAML, TOML, CSV, TSV, XML
+
+Key Features:
+- Auto-serialization of Python data to structured formats
+- Flexible path control with directory creation and overwrite handling
+- Injection of data via chaining (`last_result`)
+- Preview mode with file metadata visualization
+
+Common use cases:
+- Writing processed results to disk
+- Logging artifacts from batch pipelines
+- Exporting config or user input to JSON/YAML for reuse
+"""
 import csv
 import json
 import xml.etree.ElementTree as ET
@@ -21,13 +40,50 @@ from falyx.themes import OneColors
 
 
 class SaveFileAction(BaseAction):
-    """
+    """Saves data to a file in the specified format.
-    SaveFileAction saves data to a file in the specified format (e.g., TEXT, JSON, YAML).
-    Supports overwrite control and integrates with chaining workflows via inject_last_result.
 
-    Supported types: TEXT, JSON, YAML, TOML, CSV, TSV, XML
+    `SaveFileAction` serializes and writes input data to disk using the format
+    defined by `file_type`. It supports plain text and structured formats like
+    JSON, YAML, TOML, CSV, TSV, and XML. Files may be overwritten or appended
+    based on settings, and parent directories are created if missing.
 
-    If the file exists and overwrite is False, the action will raise a FileExistsError.
+    Data can be provided directly via the `data` argument or dynamically injected
+    from the previous Action using `inject_last_result`.
+
+    Key Features:
+    - Format-aware saving with validation
+    - Lifecycle hook support (before, success, error, after, teardown)
+    - Chain-compatible via last_result injection
+    - Supports safe overwrite behavior and preview diagnostics
+
+    Args:
+        name (str): Name of the action. Used for logging and debugging.
+        file_path (str | Path): Destination file path.
+        file_type (FileType | str): Output format (e.g., "json", "yaml", "text").
+        mode (Literal["w", "a"]): File mode—write or append. Default is "w".
+        encoding (str): Encoding to use when writing files (default: "UTF-8").
+        data (Any): Data to save. If omitted, uses last_result injection.
+        overwrite (bool): Whether to overwrite existing files. Default is True.
+        create_dirs (bool): Whether to auto-create parent directories.
+        inject_last_result (bool): Inject previous result as input if enabled.
+        inject_into (str): Name of kwarg to inject last_result into (default: "data").
+
+    Returns:
+        str: The full path to the saved file.
+
+    Raises:
+        FileExistsError: If the file exists and `overwrite` is False.
+        FileNotFoundError: If parent directory is missing and `create_dirs` is False.
+        ValueError: If data format is invalid for the target file type.
+        Exception: Any errors encountered during file writing.
+
+    Example:
+        SaveFileAction(
+            name="SaveOutput",
+            file_path="output/data.json",
+            file_type="json",
+            inject_last_result=True
+        )
     """
 
     def __init__(
@@ -36,20 +92,21 @@ class SaveFileAction(BaseAction):
         file_path: str,
         file_type: FileType | str = FileType.TEXT,
         mode: Literal["w", "a"] = "w",
+        encoding: str = "UTF-8",
         data: Any = None,
         overwrite: bool = True,
         create_dirs: bool = True,
         inject_last_result: bool = False,
         inject_into: str = "data",
     ):
-        """
+        """SaveFileAction allows saving data to a file.
-        SaveFileAction allows saving data to a file.
 
         Args:
             name (str): Name of the action.
             file_path (str | Path): Path to the file where data will be saved.
             file_type (FileType | str): Format to write to (e.g. TEXT, JSON, YAML).
             mode (Literal["w", "a"]): File mode (default: "w").
+            encoding (str): Encoding to use when writing files (default: "UTF-8").
             data (Any): Data to be saved (if not using inject_last_result).
             overwrite (bool): Whether to overwrite the file if it exists.
             create_dirs (bool): Whether to create parent directories if they do not exist.
@@ -60,11 +117,12 @@ class SaveFileAction(BaseAction):
             name=name, inject_last_result=inject_last_result, inject_into=inject_into
         )
         self._file_path = self._coerce_file_path(file_path)
-        self._file_type = self._coerce_file_type(file_type)
+        self._file_type = FileType(file_type)
         self.data = data
         self.overwrite = overwrite
         self.mode = mode
         self.create_dirs = create_dirs
+        self.encoding = encoding
 
     @property
     def file_path(self) -> Path | None:
@@ -92,20 +150,6 @@ class SaveFileAction(BaseAction):
         """Get the file type."""
         return self._file_type
 
-    @file_type.setter
-    def file_type(self, value: FileType | str):
-        """Set the file type, converting to FileType if necessary."""
-        self._file_type = self._coerce_file_type(value)
-
-    def _coerce_file_type(self, file_type: FileType | str) -> FileType:
-        """Coerce the file type to a FileType enum."""
-        if isinstance(file_type, FileType):
-            return file_type
-        elif isinstance(file_type, str):
-            return FileType(file_type)
-        else:
-            raise TypeError("file_type must be a FileType enum or string")
-
     def get_infer_target(self) -> tuple[None, None]:
         return None, None
 
@@ -143,13 +187,15 @@ class SaveFileAction(BaseAction):
 
         try:
             if self.file_type == FileType.TEXT:
-                self.file_path.write_text(data, encoding="UTF-8")
+                self.file_path.write_text(data, encoding=self.encoding)
             elif self.file_type == FileType.JSON:
-                self.file_path.write_text(json.dumps(data, indent=4), encoding="UTF-8")
+                self.file_path.write_text(
+                    json.dumps(data, indent=4), encoding=self.encoding
+                )
             elif self.file_type == FileType.TOML:
-                self.file_path.write_text(toml.dumps(data), encoding="UTF-8")
+                self.file_path.write_text(toml.dumps(data), encoding=self.encoding)
             elif self.file_type == FileType.YAML:
-                self.file_path.write_text(yaml.dump(data), encoding="UTF-8")
+                self.file_path.write_text(yaml.dump(data), encoding=self.encoding)
             elif self.file_type == FileType.CSV:
                 if not isinstance(data, list) or not all(
                     isinstance(row, list) for row in data
@@ -158,7 +204,7 @@ class SaveFileAction(BaseAction):
                         f"{self.file_type.name} file type requires a list of lists"
                     )
                 with open(
-                    self.file_path, mode=self.mode, newline="", encoding="UTF-8"
+                    self.file_path, mode=self.mode, newline="", encoding=self.encoding
                 ) as csvfile:
                     writer = csv.writer(csvfile)
                     writer.writerows(data)
@@ -170,7 +216,7 @@ class SaveFileAction(BaseAction):
                         f"{self.file_type.name} file type requires a list of lists"
                     )
                 with open(
-                    self.file_path, mode=self.mode, newline="", encoding="UTF-8"
+                    self.file_path, mode=self.mode, newline="", encoding=self.encoding
                 ) as tsvfile:
                     writer = csv.writer(tsvfile, delimiter="\t")
                     writer.writerows(data)
@@ -180,7 +226,7 @@ class SaveFileAction(BaseAction):
                 root = ET.Element("root")
                 self._dict_to_xml(data, root)
                 tree = ET.ElementTree(root)
-                tree.write(self.file_path, encoding="UTF-8", xml_declaration=True)
+                tree.write(self.file_path, encoding=self.encoding, xml_declaration=True)
             else:
                 raise ValueError(f"Unsupported file type: {self.file_type}")
 

falyx/action/select_file_action.py

@@ -1,5 +1,46 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""select_file_action.py"""
+"""Defines `SelectFileAction`, a Falyx Action that allows users to select one or more
+files from a target directory and optionally return either their content or path,
+parsed based on a selected `FileType`.
+
+This action combines rich interactive selection (via `SelectionOption`) with
+format-aware parsing, making it ideal for loading external resources, injecting
+config files, or dynamically selecting inputs mid-pipeline.
+
+Supports filtering by file suffix, customizable prompt layout, multi-select mode,
+and automatic content parsing for common formats.
+
+Key Features:
+- Lists files from a directory and renders them in a Rich-powered menu
+- Supports suffix filtering (e.g., only `.yaml` or `.json` files)
+- Returns content parsed as `str`, `dict`, `list`, or raw `Path` depending on `FileType`
+- Works in single or multi-selection mode
+- Fully compatible with Falyx hooks and context system
+- Graceful cancellation via `CancelSignal`
+
+Supported Return Types (`FileType`):
+- `TEXT`: UTF-8 string content
+- `PATH`: File path object (`Path`)
+- `JSON`, `YAML`, `TOML`: Parsed dictionaries or lists
+- `CSV`, `TSV`: `list[list[str]]` from structured rows
+- `XML`: `ElementTree.Element` root object
+
+Use Cases:
+- Prompting users to select a config file during setup
+- Dynamically loading data into chained workflows
+- CLI interfaces that require structured file ingestion
+
+Example:
+    SelectFileAction(
+        name="ChooseConfigFile",
+        directory="configs/",
+        suffix_filter=".yaml",
+        return_type="yaml",
+    )
+
+This module is ideal for use cases where file choice is deferred to runtime
+and needs to feed into structured automation pipelines.
+"""
 from __future__ import annotations
 
 import csv
@@ -19,6 +60,7 @@ from falyx.context import ExecutionContext
 from falyx.execution_registry import ExecutionRegistry as er
 from falyx.hook_manager import HookType
 from falyx.logger import logger
+from falyx.prompt_utils import rich_text_to_prompt_text
 from falyx.selection import (
     SelectionOption,
     prompt_for_selection,
@@ -29,8 +71,7 @@ from falyx.themes import OneColors
 
 
 class SelectFileAction(BaseAction):
-    """
+    """SelectFileAction allows users to select a file(s) from a directory and return:
-    SelectFileAction allows users to select a file from a directory and return:
     - file content (as text, JSON, CSV, etc.)
     - or the file path itself.
 
@@ -50,6 +91,9 @@ class SelectFileAction(BaseAction):
         style (str): Style for the selection options.
         suffix_filter (str | None): Restrict to certain file types.
         return_type (FileType): What to return (path, content, parsed).
+        number_selections (int | str): How many files to select (1, 2, '*').
+        separator (str): Separator for multiple selections.
+        allow_duplicates (bool): Allow selecting the same file multiple times.
         prompt_session (PromptSession | None): Prompt session for user input.
     """
 
@@ -64,6 +108,7 @@ class SelectFileAction(BaseAction):
         style: str = OneColors.WHITE,
         suffix_filter: str | None = None,
         return_type: FileType | str = FileType.PATH,
+        encoding: str = "UTF-8",
         number_selections: int | str = 1,
         separator: str = ",",
         allow_duplicates: bool = False,
@@ -73,14 +118,17 @@ class SelectFileAction(BaseAction):
         self.directory = Path(directory).resolve()
         self.title = title
         self.columns = columns
-        self.prompt_message = prompt_message
+        self.prompt_message = rich_text_to_prompt_text(prompt_message)
         self.suffix_filter = suffix_filter
         self.style = style
         self.number_selections = number_selections
         self.separator = separator
         self.allow_duplicates = allow_duplicates
-        self.prompt_session = prompt_session or PromptSession()
+        self.prompt_session = prompt_session or PromptSession(
-        self.return_type = self._coerce_return_type(return_type)
+            interrupt_exception=CancelSignal
+        )
+        self.return_type = FileType(return_type)
+        self.encoding = encoding
 
     @property
     def number_selections(self) -> int | str:
@@ -97,50 +145,45 @@ class SelectFileAction(BaseAction):
         else:
             raise ValueError("number_selections must be a positive integer or one of '*'")
 
-    def _coerce_return_type(self, return_type: FileType | str) -> FileType:
-        if isinstance(return_type, FileType):
-            return return_type
-        elif isinstance(return_type, str):
-            return FileType(return_type)
-        else:
-            raise TypeError("return_type must be a FileType enum or string")
-
     def get_options(self, files: list[Path]) -> dict[str, SelectionOption]:
-        value: Any
         options = {}
         for index, file in enumerate(files):
+            options[str(index)] = SelectionOption(
+                description=file.name,
+                value=file,  # Store the Path only — parsing will happen later
+                style=self.style,
+            )
+        return options
+
+    def parse_file(self, file: Path) -> Any:
+        value: Any
         try:
             if self.return_type == FileType.TEXT:
-                    value = file.read_text(encoding="UTF-8")
+                value = file.read_text(encoding=self.encoding)
             elif self.return_type == FileType.PATH:
                 value = file
             elif self.return_type == FileType.JSON:
-                    value = json.loads(file.read_text(encoding="UTF-8"))
+                value = json.loads(file.read_text(encoding=self.encoding))
             elif self.return_type == FileType.TOML:
-                    value = toml.loads(file.read_text(encoding="UTF-8"))
+                value = toml.loads(file.read_text(encoding=self.encoding))
             elif self.return_type == FileType.YAML:
-                    value = yaml.safe_load(file.read_text(encoding="UTF-8"))
+                value = yaml.safe_load(file.read_text(encoding=self.encoding))
             elif self.return_type == FileType.CSV:
-                    with open(file, newline="", encoding="UTF-8") as csvfile:
+                with open(file, newline="", encoding=self.encoding) as csvfile:
                     reader = csv.reader(csvfile)
                     value = list(reader)
             elif self.return_type == FileType.TSV:
-                    with open(file, newline="", encoding="UTF-8") as tsvfile:
+                with open(file, newline="", encoding=self.encoding) as tsvfile:
                     reader = csv.reader(tsvfile, delimiter="\t")
                     value = list(reader)
             elif self.return_type == FileType.XML:
-                    tree = ET.parse(file, parser=ET.XMLParser(encoding="UTF-8"))
+                tree = ET.parse(file, parser=ET.XMLParser(encoding=self.encoding))
-                    root = tree.getroot()
+                value = tree.getroot()
-                    value = ET.tostring(root, encoding="unicode")
             else:
                 raise ValueError(f"Unsupported return type: {self.return_type}")
-
-                options[str(index)] = SelectionOption(
-                    description=file.name, value=value, style=self.style
-                )
         except Exception as error:
             logger.error("Failed to parse %s: %s", file.name, error)
-        return options
+        return value
 
     def _find_cancel_key(self, options) -> str:
         """Return first numeric value not already used in the selection dict."""
@@ -199,9 +242,9 @@ class SelectFileAction(BaseAction):
             if isinstance(keys, str):
                 if keys == cancel_key:
                     raise CancelSignal("User canceled the selection.")
-                result = options[keys].value
+                result = self.parse_file(options[keys].value)
             elif isinstance(keys, list):
-                result = [options[key].value for key in keys]
+                result = [self.parse_file(options[key].value) for key in keys]
 
             context.result = result
             await self.hooks.trigger(HookType.ON_SUCCESS, context)
@@ -217,7 +260,7 @@ class SelectFileAction(BaseAction):
             er.record(context)
 
     async def preview(self, parent: Tree | None = None):
-        label = f"[{OneColors.GREEN}]📁 SelectFilesAction[/] '{self.name}'"
+        label = f"[{OneColors.GREEN}]📁 SelectFileAction[/] '{self.name}'"
         tree = parent.add(label) if parent else Tree(label)
 
         tree.add(f"[dim]Directory:[/] {str(self.directory)}")
@@ -225,6 +268,7 @@ class SelectFileAction(BaseAction):
         tree.add(f"[dim]Return type:[/] {self.return_type}")
         tree.add(f"[dim]Prompt:[/] {self.prompt_message}")
         tree.add(f"[dim]Columns:[/] {self.columns}")
+        tree.add("[dim]Loading:[/] Lazy (parsing occurs after selection)")
         try:
             files = list(self.directory.iterdir())
             if self.suffix_filter:
@@ -243,6 +287,6 @@ class SelectFileAction(BaseAction):
 
     def __str__(self) -> str:
         return (
-            f"SelectFilesAction(name={self.name!r}, dir={str(self.directory)!r}, "
+            f"SelectFileAction(name={self.name!r}, dir={str(self.directory)!r}, "
             f"suffix_filter={self.suffix_filter!r}, return_type={self.return_type})"
         )

falyx/action/selection_action.py

@@ -1,5 +1,35 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""selection_action.py"""
+"""Defines `SelectionAction`, a highly flexible Falyx Action for interactive or
+headless selection from a list or dictionary of user-defined options.
+
+This module powers workflows that require prompting the user for input, selecting
+configuration presets, branching execution paths, or collecting multiple values
+in a type-safe, hook-compatible, and composable way.
+
+Key Features:
+- Supports both flat lists and structured dictionaries (`SelectionOptionMap`)
+- Handles single or multi-selection with configurable separators
+- Returns results in various formats (key, value, description, item, or mapping)
+- Integrates fully with Falyx lifecycle hooks and `last_result` injection
+- Works in interactive (`prompt_toolkit`) and non-interactive (headless) modes
+- Renders a Rich-based table preview for diagnostics or dry runs
+
+Usage Scenarios:
+- Guided CLI wizards or configuration menus
+- Dynamic branching or conditional step logic
+- User-driven parameterization in chained workflows
+- Reusable pickers for environments, files, datasets, etc.
+
+Example:
+    SelectionAction(
+        name="ChooseMode",
+        selections={"dev": "Development", "prod": "Production"},
+        return_type="key"
+    )
+
+This module is foundational to creating expressive, user-centered CLI experiences
+within Falyx while preserving reproducibility and automation friendliness.
+"""
 from typing import Any
 
 from prompt_toolkit import PromptSession
@@ -11,6 +41,7 @@ from falyx.context import ExecutionContext
 from falyx.execution_registry import ExecutionRegistry as er
 from falyx.hook_manager import HookType
 from falyx.logger import logger
+from falyx.prompt_utils import rich_text_to_prompt_text
 from falyx.selection import (
     SelectionOption,
     SelectionOptionMap,
@@ -24,12 +55,65 @@ from falyx.themes import OneColors
 
 
 class SelectionAction(BaseAction):
-    """
+    """A Falyx Action for interactively or programmatically selecting one or more
-    A selection action that prompts the user to select an option from a list or
+    items from a list or dictionary of options.
-    dictionary. The selected option is then returned as the result of the action.
 
-    If return_key is True, the key of the selected option is returned instead of
+    `SelectionAction` supports both `list[str]` and `dict[str, SelectionOption]`
-    the value.
+    inputs. It renders a prompt (unless `never_prompt=True`), validates user input
+    or injected defaults, and returns a structured result based on the specified
+    `return_type`.
+
+    It is commonly used for item pickers, confirmation flows, dynamic parameterization,
+    or guided workflows in interactive or headless CLI pipelines.
+
+    Features:
+    - Supports single or multiple selections (`number_selections`)
+    - Dictionary mode allows rich metadata (description, value, style)
+    - Flexible return values: key(s), value(s), item(s), description(s), or mappings
+    - Fully hookable lifecycle (`before`, `on_success`, `on_error`, `after`, `on_teardown`)
+    - Default selection logic supports previous results (`last_result`)
+    - Can run in headless mode using `never_prompt` and fallback defaults
+
+    Args:
+        name (str): Action name for tracking and logging.
+        selections (list[str] | dict[str, SelectionOption] | dict[str, Any]):
+            The available choices. If a plain dict is passed, values are converted
+            into `SelectionOption` instances.
+        title (str): Title shown in the selection UI (default: "Select an option").
+        columns (int): Number of columns in the selection table.
+        prompt_message (str): Input prompt for the user (default: "Select > ").
+        default_selection (str | list[str]): Key(s) or index(es) used as fallback selection.
+        number_selections (int | str): Max number of choices allowed (or "*" for unlimited).
+        separator (str): Character used to separate multi-selections (default: ",").
+        allow_duplicates (bool): Whether duplicate selections are allowed.
+        inject_last_result (bool): If True, attempts to inject the last result as default.
+        inject_into (str): The keyword name for injected value (default: "last_result").
+        return_type (SelectionReturnType | str): The type of result to return. Options:
+            - KEY: Return the selected key(s) only.
+            - VALUE: Return the value(s) associated with the selected key(s).
+            - DESCRIPTION: Return the description(s) of the selected item(s).
+            - DESCRIPTION_VALUE: Return a dict of {description: value} pairs.
+            - ITEMS: Return full `SelectionOption` objects as a dict {key: SelectionOption}.
+        prompt_session (PromptSession | None): Reused or customized prompt_toolkit session.
+        never_prompt (bool): If True, skips prompting and uses default_selection or last_result.
+        show_table (bool): Whether to render the selection table before prompting.
+
+    Returns:
+        Any: The selected result(s), shaped according to `return_type`.
+
+    Raises:
+        CancelSignal: If the user chooses the cancel option.
+        ValueError: If configuration is invalid or no selection can be resolved.
+        TypeError: If `selections` is not a supported type.
+
+    Example:
+        SelectionAction(
+            name="PickEnv",
+            selections={"dev": "Development", "prod": "Production"},
+            return_type="key",
+        )
+
+    This Action supports use in both interactive menus and chained, non-interactive CLI flows.
     """
 
     def __init__(
@@ -46,7 +130,7 @@ class SelectionAction(BaseAction):
         title: str = "Select an option",
         columns: int = 5,
         prompt_message: str = "Select > ",
-        default_selection: str = "",
+        default_selection: str | list[str] = "",
         number_selections: int | str = 1,
         separator: str = ",",
         allow_duplicates: bool = False,
@@ -65,15 +149,17 @@ class SelectionAction(BaseAction):
         )
         # Setter normalizes to correct type, mypy can't infer that
         self.selections: list[str] | SelectionOptionMap = selections  # type: ignore[assignment]
-        self.return_type: SelectionReturnType = self._coerce_return_type(return_type)
+        self.return_type: SelectionReturnType = SelectionReturnType(return_type)
         self.title = title
         self.columns = columns
-        self.prompt_session = prompt_session or PromptSession()
+        self.prompt_session = prompt_session or PromptSession(
+            interrupt_exception=CancelSignal
+        )
         self.default_selection = default_selection
         self.number_selections = number_selections
         self.separator = separator
         self.allow_duplicates = allow_duplicates
-        self.prompt_message = prompt_message
+        self.prompt_message = rich_text_to_prompt_text(prompt_message)
         self.show_table = show_table
 
     @property
@@ -91,13 +177,6 @@ class SelectionAction(BaseAction):
         else:
             raise ValueError("number_selections must be a positive integer or '*'")
 
-    def _coerce_return_type(
-        self, return_type: SelectionReturnType | str
-    ) -> SelectionReturnType:
-        if isinstance(return_type, SelectionReturnType):
-            return return_type
-        return SelectionReturnType(return_type)
-
     @property
     def selections(self) -> list[str] | SelectionOptionMap:
         return self._selections
@@ -202,6 +281,95 @@ class SelectionAction(BaseAction):
             raise ValueError(f"Unsupported return type: {self.return_type}")
         return result
 
+    async def _resolve_effective_default(self) -> str:
+        effective_default: str | list[str] = self.default_selection
+        maybe_result = self.last_result
+        if self.number_selections == 1:
+            if isinstance(effective_default, list):
+                effective_default = effective_default[0] if effective_default else ""
+            elif isinstance(maybe_result, list):
+                maybe_result = maybe_result[0] if maybe_result else ""
+            default = await self._resolve_single_default(maybe_result)
+            if not default:
+                default = await self._resolve_single_default(effective_default)
+            if not default and self.inject_last_result:
+                logger.warning(
+                    "[%s] Injected last result '%s' not found in selections",
+                    self.name,
+                    maybe_result,
+                )
+            return default
+
+        if maybe_result and isinstance(maybe_result, list):
+            maybe_result = [
+                await self._resolve_single_default(item) for item in maybe_result
+            ]
+            if (
+                maybe_result
+                and self.number_selections != "*"
+                and len(maybe_result) != self.number_selections
+            ):
+                raise ValueError(
+                    f"[{self.name}] 'number_selections' is {self.number_selections}, "
+                    f"but last_result has a different length: {len(maybe_result)}."
+                )
+            return self.separator.join(maybe_result)
+        elif effective_default and isinstance(effective_default, list):
+            effective_default = [
+                await self._resolve_single_default(item) for item in effective_default
+            ]
+            if (
+                effective_default
+                and self.number_selections != "*"
+                and len(effective_default) != self.number_selections
+            ):
+                raise ValueError(
+                    f"[{self.name}] 'number_selections' is {self.number_selections}, "
+                    f"but default_selection has a different length: {len(effective_default)}."
+                )
+            return self.separator.join(effective_default)
+        if self.inject_last_result:
+            logger.warning(
+                "[%s] Injected last result '%s' not found in selections",
+                self.name,
+                maybe_result,
+            )
+        return ""
+
+    async def _resolve_single_default(self, maybe_result: str) -> str:
+        effective_default = ""
+        if isinstance(self.selections, dict):
+            if str(maybe_result) in self.selections:
+                effective_default = str(maybe_result)
+            elif maybe_result in (
+                selection.value for selection in self.selections.values()
+            ):
+                selection = [
+                    key
+                    for key, sel in self.selections.items()
+                    if sel.value == maybe_result and maybe_result is not None
+                ]
+                if selection:
+                    effective_default = selection[0]
+            elif maybe_result in (
+                selection.description for selection in self.selections.values()
+            ):
+                selection = [
+                    key
+                    for key, sel in self.selections.items()
+                    if sel.description == maybe_result
+                ]
+                if selection:
+                    effective_default = selection[0]
+        elif isinstance(self.selections, list):
+            if str(maybe_result).isdigit() and int(maybe_result) in range(
+                len(self.selections)
+            ):
+                effective_default = maybe_result
+            elif maybe_result in self.selections:
+                effective_default = str(self.selections.index(maybe_result))
+        return effective_default
+
     async def _run(self, *args, **kwargs) -> Any:
         kwargs = self._maybe_inject_last_result(kwargs)
         context = ExecutionContext(
@@ -211,28 +379,7 @@ class SelectionAction(BaseAction):
             action=self,
         )
 
-        effective_default = str(self.default_selection)
+        effective_default = await self._resolve_effective_default()
-        maybe_result = str(self.last_result)
-        if isinstance(self.selections, dict):
-            if maybe_result in self.selections:
-                effective_default = maybe_result
-            elif self.inject_last_result:
-                logger.warning(
-                    "[%s] Injected last result '%s' not found in selections",
-                    self.name,
-                    maybe_result,
-                )
-        elif isinstance(self.selections, list):
-            if maybe_result.isdigit() and int(maybe_result) in range(
-                len(self.selections)
-            ):
-                effective_default = maybe_result
-            elif self.inject_last_result:
-                logger.warning(
-                    "[%s] Injected last result '%s' not found in selections",
-                    self.name,
-                    maybe_result,
-                )
 
         if self.never_prompt and not effective_default:
             raise ValueError(
@@ -251,6 +398,9 @@ class SelectionAction(BaseAction):
                     columns=self.columns,
                     formatter=self.cancel_formatter,
                 )
+                if effective_default is None or isinstance(effective_default, int):
+                    effective_default = ""
+
                 if not self.never_prompt:
                     indices: int | list[int] = await prompt_for_index(
                         len(self.selections),
@@ -265,8 +415,13 @@ class SelectionAction(BaseAction):
                         cancel_key=self.cancel_key,
                     )
                 else:
-                    if effective_default:
+                    if effective_default and self.number_selections == 1:
                         indices = int(effective_default)
+                    elif effective_default:
+                        indices = [
+                            int(index)
+                            for index in effective_default.split(self.separator)
+                        ]
                     else:
                         raise ValueError(
                             f"[{self.name}] 'never_prompt' is True but no valid "
@@ -308,7 +463,15 @@ class SelectionAction(BaseAction):
                         cancel_key=self.cancel_key,
                     )
                 else:
+                    if effective_default and self.number_selections == 1:
                         keys = effective_default
+                    elif effective_default:
+                        keys = effective_default.split(self.separator)
+                    else:
+                        raise ValueError(
+                            f"[{self.name}] 'never_prompt' is True but no valid "
+                            "default_selection was provided."
+                        )
                 if keys == self.cancel_key:
                     raise CancelSignal("User cancelled the selection.")
 
@@ -337,13 +500,13 @@ class SelectionAction(BaseAction):
 
         if isinstance(self.selections, list):
             sub = tree.add(f"[dim]Type:[/] List[str] ({len(self.selections)} items)")
-            for i, item in enumerate(self.selections[:10]):  # limit to 10
+            for i, item in enumerate(self.selections[:10]):
                 sub.add(f"[dim]{i}[/]: {item}")
             if len(self.selections) > 10:
                 sub.add(f"[dim]... ({len(self.selections) - 10} more)[/]")
         elif isinstance(self.selections, dict):
             sub = tree.add(
-                f"[dim]Type:[/] Dict[str, (str, Any)] ({len(self.selections)} items)"
+                f"[dim]Type:[/] Dict[str, SelectionOption] ({len(self.selections)} items)"
             )
             for i, (key, option) in enumerate(list(self.selections.items())[:10]):
                 sub.add(f"[dim]{key}[/]: {option.description}")
@@ -353,9 +516,30 @@ class SelectionAction(BaseAction):
             tree.add(f"[{OneColors.DARK_RED_b}]Invalid selections type[/]")
             return
 
-        tree.add(f"[dim]Default:[/] '{self.default_selection or self.last_result}'")
+        default = self.default_selection or self.last_result
-        tree.add(f"[dim]Return:[/] {self.return_type.name.capitalize()}")
+        if isinstance(default, list):
+            default_display = self.separator.join(str(d) for d in default)
+        else:
+            default_display = str(default or "")
+
+        tree.add(f"[dim]Default:[/] '{default_display}'")
+
+        return_behavior = {
+            "KEY": "selected key(s)",
+            "VALUE": "mapped value(s)",
+            "DESCRIPTION": "description(s)",
+            "ITEMS": "SelectionOption object(s)",
+            "DESCRIPTION_VALUE": "{description: value}",
+        }.get(self.return_type.name, self.return_type.name)
+
+        tree.add(
+            f"[dim]Return:[/] {self.return_type.name.capitalize()} → {return_behavior}"
+        )
         tree.add(f"[dim]Prompt:[/] {'Disabled' if self.never_prompt else 'Enabled'}")
+        tree.add(f"[dim]Columns:[/] {self.columns}")
+        tree.add(
+            f"[dim]Multi-select:[/] {'Yes' if self.number_selections != 1 else 'No'}"
+        )
 
         if not parent:
             self.console.print(tree)

falyx/action/shell_action.py

@@ -1,6 +1,5 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""shell_action.py
+"""Execute shell commands with input substitution."""
-Execute shell commands with input substitution."""
 
 from __future__ import annotations
 
@@ -17,8 +16,7 @@ from falyx.themes import OneColors
 
 
 class ShellAction(BaseIOAction):
-    """
+    """ShellAction wraps a shell command template for CLI pipelines.
-    ShellAction wraps a shell command template for CLI pipelines.
 
     This Action takes parsed input (from stdin, literal, or last_result),
     substitutes it into the provided shell command template, and executes

falyx/action/signal_action.py

@@ -1,32 +1,81 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""signal_action.py"""
+"""Defines `SignalAction`, a lightweight Falyx Action that raises a `FlowSignal`
+(such as `BackSignal`, `QuitSignal`, or `BreakChainSignal`) during execution to
+alter or exit the CLI flow.
+
+Unlike traditional actions, `SignalAction` does not return a result—instead, it raises
+a signal to break, back out, or exit gracefully. Despite its minimal behavior,
+it fully supports Falyx's hook lifecycle, including `before`, `on_error`, `after`,
+and `on_teardown`—allowing it to trigger logging, audit events, UI updates, or custom
+telemetry before halting flow.
+
+Key Features:
+- Declaratively raises a `FlowSignal` from within any Falyx workflow
+- Works in menus, chained actions, or conditionals
+- Hook-compatible: can run pre- and post-signal lifecycle hooks
+- Supports previewing and structured introspection
+
+Use Cases:
+- Implementing "Back", "Cancel", or "Quit" options in `MenuAction` or `PromptMenuAction`
+- Triggering an intentional early exit from a `ChainedAction`
+- Running cleanup hooks before stopping execution
+
+Example:
+    SignalAction("ExitApp", QuitSignal(), hooks=my_hook_manager)
+"""
 from rich.tree import Tree
 
 from falyx.action.action import Action
+from falyx.hook_manager import HookManager
 from falyx.signals import FlowSignal
 from falyx.themes import OneColors
 
 
 class SignalAction(Action):
-    """
+    """A hook-compatible action that raises a control flow signal when invoked.
-    An action that raises a control flow signal when executed.
 
-    Useful for exiting a menu, going back, or halting execution gracefully.
+    `SignalAction` raises a `FlowSignal` (e.g., `BackSignal`, `QuitSignal`,
+    `BreakChainSignal`) during execution. It is commonly used to exit menus,
+    break from chained actions, or halt workflows intentionally.
+
+    Even though the signal interrupts normal flow, all registered lifecycle hooks
+    (`before`, `on_error`, `after`, `on_teardown`) are triggered as expected—
+    allowing structured behavior such as logging, analytics, or UI changes
+    before the signal is raised.
+
+    Args:
+        name (str): Name of the action (used for logging and debugging).
+        signal (FlowSignal): A subclass of `FlowSignal` to raise (e.g., QuitSignal).
+        hooks (HookManager | None): Optional hook manager to attach lifecycle hooks.
+
+    Raises:
+        FlowSignal: Always raises the provided signal when the action is run.
     """
 
-    def __init__(self, name: str, signal: FlowSignal):
+    def __init__(self, name: str, signal: FlowSignal, hooks: HookManager | None = None):
         self.signal = signal
-        super().__init__(name, action=self.raise_signal)
+        super().__init__(name, action=self.raise_signal, hooks=hooks)
 
     async def raise_signal(self, *args, **kwargs):
+        """Raises the configured `FlowSignal`.
+
+        This method is called internally by the Falyx runtime and is the core
+        behavior of the action. All hooks surrounding execution are still triggered.
+        """
         raise self.signal
 
     @property
     def signal(self):
+        """Returns the configured `FlowSignal` instance."""
         return self._signal
 
     @signal.setter
     def signal(self, value: FlowSignal):
+        """Validates that the provided value is a `FlowSignal`.
+
+        Raises:
+            TypeError: If `value` is not an instance of `FlowSignal`.
+        """
         if not isinstance(value, FlowSignal):
             raise TypeError(
                 f"Signal must be an FlowSignal instance, got {type(value).__name__}"

falyx/action/user_input_action.py

@@ -1,5 +1,30 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""user_input_action.py"""
+"""Defines `UserInputAction`, a Falyx Action that prompts the user for input using
+Prompt Toolkit and returns the result as a string.
+
+This action is ideal for interactive CLI workflows that require user input mid-pipeline.
+It supports dynamic prompt interpolation, prompt validation, default text fallback,
+and full lifecycle hook execution.
+
+Key Features:
+- Rich Prompt Toolkit integration for input and validation
+- Dynamic prompt formatting using `last_result` injection
+- Optional `Validator` support for structured input (e.g., emails, numbers)
+- Hook lifecycle compatibility (before, on_success, on_error, after, teardown)
+- Preview support for introspection or dry-run flows
+
+Use Cases:
+- Asking for confirmation text or field input mid-chain
+- Injecting user-provided variables into automated pipelines
+- Interactive menu or wizard experiences
+
+Example:
+    UserInputAction(
+        name="GetUsername",
+        prompt_message="Enter your username > ",
+        validator=Validator.from_callable(lambda s: len(s) > 0),
+    )
+"""
 from prompt_toolkit import PromptSession
 from prompt_toolkit.validation import Validator
 from rich.tree import Tree
@@ -8,28 +33,35 @@ from falyx.action.base_action import BaseAction
 from falyx.context import ExecutionContext
 from falyx.execution_registry import ExecutionRegistry as er
 from falyx.hook_manager import HookType
+from falyx.prompt_utils import rich_text_to_prompt_text
+from falyx.signals import CancelSignal
 from falyx.themes.colors import OneColors
 
 
 class UserInputAction(BaseAction):
-    """
+    """Prompts the user for textual input and returns their response.
-    Prompts the user for input via PromptSession and returns the result.
+
+    `UserInputAction` uses Prompt Toolkit to gather input with optional validation,
+    lifecycle hook compatibility, and support for default text. If `inject_last_result`
+    is enabled, the prompt message can interpolate `{last_result}` dynamically.
 
     Args:
-        name (str): Action name.
+        name (str): Name of the action (used for introspection and logging).
-        prompt_text (str): Prompt text (can include '{last_result}' for interpolation).
+        prompt_message (str): The prompt message shown to the user.
-        validator (Validator, optional): Prompt Toolkit validator.
+            Can include `{last_result}` if `inject_last_result=True`.
-        prompt_session (PromptSession, optional): Reusable prompt session.
+        default_text (str): Optional default value shown in the prompt.
-        inject_last_result (bool): Whether to inject last_result into prompt.
+        validator (Validator | None): Prompt Toolkit validator for input constraints.
-        inject_into (str): Key to use for injection (default: 'last_result').
+        prompt_session (PromptSession | None): Optional custom prompt session.
+        inject_last_result (bool): Whether to inject `last_result` into the prompt.
     """
 
     def __init__(
         self,
         name: str,
         *,
-        prompt_text: str = "Input > ",
+        prompt_message: str = "Input > ",
         default_text: str = "",
+        multiline: bool = False,
         validator: Validator | None = None,
         prompt_session: PromptSession | None = None,
         inject_last_result: bool = False,
@@ -38,10 +70,13 @@ class UserInputAction(BaseAction):
             name=name,
             inject_last_result=inject_last_result,
         )
-        self.prompt_text = prompt_text
+        self.prompt_message = prompt_message
-        self.validator = validator
-        self.prompt_session = prompt_session or PromptSession()
         self.default_text = default_text
+        self.multiline = multiline
+        self.validator = validator
+        self.prompt_session = prompt_session or PromptSession(
+            interrupt_exception=CancelSignal
+        )
 
     def get_infer_target(self) -> tuple[None, None]:
         return None, None
@@ -57,14 +92,15 @@ class UserInputAction(BaseAction):
         try:
             await self.hooks.trigger(HookType.BEFORE, context)
 
-            prompt_text = self.prompt_text
+            prompt_message = self.prompt_message
             if self.inject_last_result and self.last_result:
-                prompt_text = prompt_text.format(last_result=self.last_result)
+                prompt_message = prompt_message.format(last_result=self.last_result)
 
             answer = await self.prompt_session.prompt_async(
-                prompt_text,
+                rich_text_to_prompt_text(prompt_message),
                 validator=self.validator,
                 default=kwargs.get("default_text", self.default_text),
+                multiline=self.multiline,
             )
             context.result = answer
             await self.hooks.trigger(HookType.ON_SUCCESS, context)
@@ -83,12 +119,12 @@ class UserInputAction(BaseAction):
         label = f"[{OneColors.MAGENTA}]⌨ UserInputAction[/] '{self.name}'"
         tree = parent.add(label) if parent else Tree(label)
 
-        prompt_text = (
+        prompt_message = (
-            self.prompt_text.replace("{last_result}", "<last_result>")
+            self.prompt_message.replace("{last_result}", "<last_result>")
-            if "{last_result}" in self.prompt_text
+            if "{last_result}" in self.prompt_message
-            else self.prompt_text
+            else self.prompt_message
         )
-        tree.add(f"[dim]Prompt:[/] {prompt_text}")
+        tree.add(f"[dim]Prompt:[/] {prompt_message}")
         if self.validator:
             tree.add("[dim]Validator:[/] Yes")
         if not parent:

falyx/bottom_bar.py

@@ -1,10 +1,43 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""bottom_bar.py"""
+"""Provides the `BottomBar` class for managing a customizable bottom status bar in
+Falyx-based CLI applications.
+
+The bottom bar is rendered using `prompt_toolkit` and supports:
+- Rich-formatted static content
+- Live-updating value trackers and counters
+- Toggle switches activated via Ctrl+<key> bindings
+- Config-driven visual and behavioral controls
+
+Each item in the bar is registered by name and rendered in columns across the
+bottom of the terminal. Toggles are linked to user-defined state accessors and
+mutators, and can be automatically bound to `OptionsManager` values for full
+integration with Falyx CLI argument parsing.
+
+Key Features:
+- Live rendering of structured status items using Rich-style HTML
+- Custom or built-in item types: static text, dynamic counters, toggles, value displays
+- Ctrl+key toggle handling via `prompt_toolkit.KeyBindings`
+- Columnar layout with automatic width scaling
+- Optional integration with `OptionsManager` for dynamic state toggling
+
+Example:
+    ```
+    bar = BottomBar(columns=3)
+    bar.add_static("env", "ENV: dev")
+    bar.add_toggle("d", "Debug", get_debug, toggle_debug)
+    bar.add_value_tracker("attempts", "Retries", get_retry_count)
+    bar.render()
+    ```
+
+Used by Falyx to provide a persistent UI element showing toggles, system state,
+and runtime telemetry below the input prompt.
+"""
 
 from typing import Any, Callable
 
 from prompt_toolkit.formatted_text import HTML, merge_formatted_text
 from prompt_toolkit.key_binding import KeyBindings
+from prompt_toolkit.key_binding.key_processor import KeyPressEvent
 from rich.console import Console
 
 from falyx.console import console
@@ -24,11 +57,12 @@ class BottomBar:
             Must return True if key is available, otherwise False.
     """
 
+    RESERVED_CTRL_KEYS = {"c", "d", "z", "v"}
+
     def __init__(
         self,
         columns: int = 3,
         key_bindings: KeyBindings | None = None,
-        key_validator: Callable[[str], bool] | None = None,
     ) -> None:
         self.columns = columns
         self.console: Console = console
@@ -36,7 +70,11 @@ class BottomBar:
         self._value_getters: dict[str, Callable[[], Any]] = CaseInsensitiveDict()
         self.toggle_keys: list[str] = []
         self.key_bindings = key_bindings or KeyBindings()
-        self.key_validator = key_validator
+
+    @property
+    def has_items(self) -> bool:
+        """Check if the bottom bar has any registered items."""
+        return bool(self._named_items)
 
     @staticmethod
     def default_render(label: str, value: Any, fg: str, bg: str, width: int) -> HTML:
@@ -121,17 +159,31 @@ class BottomBar:
         bg_on: str = OneColors.GREEN,
         bg_off: str = OneColors.DARK_RED,
     ) -> None:
+        """
+        Add a toggle to the bottom bar.
+        Always uses the ctrl + key combination for toggling.
+
+        Args:
+            key (str): The key to toggle the state.
+            label (str): The label for the toggle.
+            get_state (Callable[[], bool]): Function to get the current state.
+            toggle_state (Callable[[], None]): Function to toggle the state.
+            fg (str): Foreground color for the label.
+            bg_on (str): Background color when the toggle is ON.
+            bg_off (str): Background color when the toggle is OFF.
+        """
+        key = key.lower()
+        if key in self.RESERVED_CTRL_KEYS:
+            raise ValueError(
+                f"'{key}' is a reserved terminal control key and cannot be used for toggles."
+            )
         if not callable(get_state):
             raise ValueError("`get_state` must be a callable returning bool")
         if not callable(toggle_state):
             raise ValueError("`toggle_state` must be a callable")
-        key = key.upper()
         if key in self.toggle_keys:
             raise ValueError(f"Key {key} is already used as a toggle")
-        if self.key_validator and not self.key_validator(key):
+
-            raise ValueError(
-                f"Key '{key}' conflicts with existing command, toggle, or reserved key."
-            )
         self._value_getters[key] = get_state
         self.toggle_keys.append(key)
 
@@ -139,15 +191,13 @@ class BottomBar:
             get_state_ = self._value_getters[key]
             color = bg_on if get_state_() else bg_off
             status = "ON" if get_state_() else "OFF"
-            text = f"({key.upper()}) {label}: {status}"
+            text = f"(^{key.lower()}) {label}: {status}"
             return HTML(f"<style bg='{color}' fg='{fg}'>{text:^{self.space}}</style>")
 
         self._add_named(key, render)
 
-        for k in (key.upper(), key.lower()):
+        @self.key_bindings.add(f"c-{key.lower()}", eager=True)
-
+        def _(_: KeyPressEvent):
-            @self.key_bindings.add(k)
-            def _(_):
             toggle_state()
 
     def add_toggle_from_option(
@@ -156,7 +206,7 @@ class BottomBar:
         label: str,
         options: OptionsManager,
         option_name: str,
-        namespace_name: str = "cli_args",
+        namespace_name: str = "default",
         fg: str = OneColors.BLACK,
         bg_on: str = OneColors.GREEN,
         bg_off: str = OneColors.DARK_RED,

falyx/command.py

@@ -1,20 +1,43 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""command.py
+"""Command abstraction for the Falyx CLI framework.
 
-Defines the Command class for Falyx CLI.
+This module defines the `Command` class, which represents a single executable
+unit exposed to users via CLI or interactive menu interfaces.
 
-Commands are callable units representing a menu option or CLI task,
+A `Command` acts as a bridge between:
-wrapping either a BaseAction or a simple function. They provide:
+- User input (parsed via CommandArgumentParser)
+- Execution logic (encapsulated in Action / BaseAction)
+- Runtime configuration (OptionsManager)
+- Lifecycle hooks (HookManager)
 
-- Hook lifecycle (before, on_success, on_error, after, on_teardown)
+Core Responsibilities:
+- Define command identity (key, aliases, description)
+- Bind an executable action or workflow
+- Configure argument parsing via CommandArgumentParser
+- Separate execution arguments (e.g. retries, confirm) from action arguments
+- Manage lifecycle hooks for command-level execution
+- Provide help, usage, and preview interfaces
 - Execution timing and duration tracking
-- Retry logic (single action or recursively through action trees)
 - Confirmation prompts and spinner integration
-- Result capturing and summary logging
-- Rich-based preview for CLI display
 
-Every Command is self-contained, configurable, and plays a critical role
+Execution Model:
-in building robust interactive menus.
+1. CLI input is routed via FalyxParser into a resolved Command
+2. Arguments are parsed via CommandArgumentParser
+3. Parsed values are split into:
+   - positional args
+   - keyword args
+   - execution args (e.g. retries, summary)
+4. Execution occurs via the bound Action with lifecycle hooks applied
+5. Results and context are tracked via ExecutionContext / ExecutionRegistry
+
+Key Concepts:
+- Commands are *user-facing entrypoints*, not execution units themselves
+- Execution is always delegated to an underlying Action or callable
+- Argument parsing is declarative and optional
+- Execution options are handled separately from business logic inputs
+
+This module defines the primary abstraction used by Falyx to expose structured,
+composable workflows as CLI commands.
 """
 from __future__ import annotations
 
@@ -23,15 +46,19 @@ from typing import Any, Awaitable, Callable
 
 from prompt_toolkit.formatted_text import FormattedText
 from pydantic import BaseModel, ConfigDict, Field, PrivateAttr, field_validator
+from rich.style import Style
 from rich.tree import Tree
 
 from falyx.action.action import Action
 from falyx.action.base_action import BaseAction
 from falyx.console import console
-from falyx.context import ExecutionContext
+from falyx.context import ExecutionContext, InvocationContext
 from falyx.debug import register_debug_hooks
+from falyx.exceptions import CommandArgumentError, InvalidHookError, NotAFalyxError
+from falyx.execution_option import ExecutionOption
 from falyx.execution_registry import ExecutionRegistry as er
 from falyx.hook_manager import HookManager, HookType
+from falyx.hooks import spinner_before_hook, spinner_teardown_hook
 from falyx.logger import logger
 from falyx.options_manager import OptionsManager
 from falyx.parser.command_argument_parser import CommandArgumentParser
@@ -46,65 +73,104 @@ from falyx.utils import ensure_async
 
 
 class Command(BaseModel):
-    """
+    """Represents a user-invokable command in Falyx.
-    Represents a selectable command in a Falyx menu system.
 
-    A Command wraps an executable action (function, coroutine, or BaseAction)
+    A `Command` encapsulates all metadata, parsing logic, and execution behavior
-    and enhances it with:
+    required to expose a callable workflow through the Falyx CLI or interactive
+    menu system.
 
-    - Lifecycle hooks (before, success, error, after, teardown)
+    It is responsible for:
-    - Retry support (single action or recursive for chained/grouped actions)
+    - Identifying the command via key and aliases
-    - Confirmation prompts for safe execution
+    - Binding an executable Action or callable
-    - Spinner visuals during execution
+    - Parsing user-provided arguments
-    - Tagging for categorization and filtering
+    - Managing execution configuration (retries, confirmation, etc.)
-    - Rich-based CLI previews
+    - Integrating with lifecycle hooks and execution context
+
+    Architecture:
+    - Parsing is delegated to CommandArgumentParser
+    - Execution is delegated to BaseAction / Action
+    - Runtime configuration is managed via OptionsManager
+    - Lifecycle hooks are managed via HookManager
+
+    Argument Handling:
+    - Supports positional and keyword arguments via CommandArgumentParser
+    - Separates execution-specific options (e.g. retries, confirm flags)
+      from action arguments
+    - Returns structured `(args, kwargs, execution_args)` for execution
+
+    Execution Behavior:
+    - Callable via `await command(*args, **kwargs)`
+    - Applies lifecycle hooks:
+        before → on_success/on_error → after → on_teardown
+    - Supports preview mode for dry-run introspection
+    - Supports retry policies and confirmation flows
     - Result tracking and summary reporting
 
-    Commands are built to be flexible yet robust, enabling dynamic CLI workflows
+    Help & Introspection:
-    without sacrificing control or reliability.
+    - Provides usage, help text, and TLDR examples
+    - Supports both CLI help and interactive menu rendering
+    - Can expose simplified or full help signatures
 
-    Attributes:
+    Args:
-        key (str): Primary trigger key for the command.
+        key (str): Primary identifier used to invoke the command.
         description (str): Short description for the menu display.
-        hidden (bool): Toggles visibility in the menu.
+        action (BaseAction | Callable[..., Any]):
-        aliases (list[str]): Alternate keys or phrases.
+            Execution logic for the command.
-        action (BaseAction | Callable): The executable logic.
+        args (tuple, optional): Static positional arguments.
-        args (tuple): Static positional arguments.
+        kwargs (dict[str, Any], optional): Static keyword arguments.
-        kwargs (dict): Static keyword arguments.
+        hidden (bool): Whether to hide the command from menus.
-        help_text (str): Additional help or guidance text.
+        aliases (list[str], optional): Alternate names for invocation.
-        style (str): Rich style for description.
+        help_text (str): Help description shown in CLI/menu.
-        confirm (bool): Whether to require confirmation before executing.
+        help_epilog (str): Additional help content.
-        confirm_message (str): Custom confirmation prompt.
+        style (Style | str): Rich style used for rendering.
-        preview_before_confirm (bool): Whether to preview before confirming.
+        confirm (bool): Whether confirmation is required before execution.
-        spinner (bool): Whether to show a spinner during execution.
+        confirm_message (str): Confirmation prompt text.
-        spinner_message (str): Spinner text message.
+        preview_before_confirm (bool): Whether to preview before confirmation.
-        spinner_type (str): Spinner style (e.g., dots, line, etc.).
+        spinner (bool): Enable spinner during execution.
-        spinner_style (str): Color or style of the spinner.
+        spinner_message (str): Spinner message text.
-        spinner_kwargs (dict): Extra spinner configuration.
+        spinner_type (str): Rich Spinner animation type (e.g., dots, line, etc.).
-        hooks (HookManager): Hook manager for lifecycle events.
+        spinner_style (Style | str): Rich style for the spinner.
-        retry (bool): Enable retry on failure.
+        spinner_speed (float): Spinner speed multiplier.
-        retry_all (bool): Enable retry across chained or grouped actions.
+        hooks (HookManager | None): Hook manager for lifecycle events.
-        retry_policy (RetryPolicy): Retry behavior configuration.
+        tags (list[str], optional): Tags for grouping and filtering.
-        tags (list[str]): Organizational tags for the command.
+        logging_hooks (bool): Enable debug logging hooks.
-        logging_hooks (bool): Whether to attach logging hooks automatically.
+        retry (bool): Enable retry behavior.
-        options_manager (OptionsManager): Manages global command-line options.
+        retry_all (bool): Apply retry to all nested actions.
-        arg_parser (CommandArgumentParser): Parses command arguments.
+        retry_policy (RetryPolicy | None): Retry configuration.
-        arguments (list[dict[str, Any]]): Argument definitions for the command.
+        arg_parser (CommandArgumentParser | None):
-        argument_config (Callable[[CommandArgumentParser], None] | None): Function to configure arguments
+            Custom argument parser instance.
-            for the command parser.
+        execution_options (frozenset[ExecutionOption], optional):
-        arg_metadata (dict[str, str | dict[str, Any]]): Metadata for arguments,
+            Enabled execution-level options.
-            such as help text or choices.
+        arguments (list[dict[str, Any]], optional):
-        simple_help_signature (bool): Whether to use a simplified help signature.
+            Declarative argument definitions.
-        custom_parser (ArgParserProtocol | None): Custom argument parser.
+        argument_config (Callable[[CommandArgumentParser], None] | None):
-        custom_help (Callable[[], str | None] | None): Custom help message generator.
+            Callback to configure parser.
-        auto_args (bool): Automatically infer arguments from the action.
+        custom_parser (ArgParserProtocol | None):
+            Override parser logic entirely.
+        custom_help (Callable[[], str | None] | None):
+            Override help rendering.
+        custom_tldr (Callable[[], str | None] | None):
+            Override TLDR rendering.
+        custom_usage (Callable[[], str | None] | None):
+            Override usage rendering.
+        auto_args (bool): Auto-generate arguments from action signature.
+        arg_metadata (dict[str, Any], optional): Metadata for arguments.
+        simple_help_signature (bool): Use simplified help formatting.
+        ignore_in_history (bool):
+            Ignore command for `last_result` in execution history.
+        options_manager (OptionsManager | None):
+            Shared options manager instance.
+        program (str | None): The parent program name.
 
-    Methods:
+    Raises:
-        __call__(): Executes the command, respecting hooks and retries.
+        CommandArgumentError: If argument parsing fails.
-        preview(): Rich tree preview of the command.
+        InvalidActionError: If action is not callable or invalid.
-        confirmation_prompt(): Formatted prompt for confirmation.
+        FalyxError: If command configuration is invalid.
-        result: Property exposing the last result.
+
-        log_summary(): Summarizes execution details to the console.
+    Notes:
+        - Commands are lightweight wrappers; execution logic belongs in Actions
+        - Argument parsing and execution are intentionally decoupled
+        - Commands are case-insensitive and support alias resolution
     """
 
     key: str
@@ -116,15 +182,15 @@ class Command(BaseModel):
     aliases: list[str] = Field(default_factory=list)
     help_text: str = ""
     help_epilog: str = ""
-    style: str = OneColors.WHITE
+    style: Style | str = OneColors.WHITE
     confirm: bool = False
     confirm_message: str = "Are you sure?"
     preview_before_confirm: bool = True
     spinner: bool = False
     spinner_message: str = "Processing..."
     spinner_type: str = "dots"
-    spinner_style: str = OneColors.CYAN
+    spinner_style: Style | str = OneColors.CYAN
-    spinner_kwargs: dict[str, Any] = Field(default_factory=dict)
+    spinner_speed: float = 1.0
     hooks: "HookManager" = Field(default_factory=HookManager)
     retry: bool = False
     retry_all: bool = False
@@ -133,64 +199,121 @@ class Command(BaseModel):
     logging_hooks: bool = False
     options_manager: OptionsManager = Field(default_factory=OptionsManager)
     arg_parser: CommandArgumentParser | None = None
+    execution_options: frozenset[ExecutionOption] = Field(default_factory=frozenset)
     arguments: list[dict[str, Any]] = Field(default_factory=list)
     argument_config: Callable[[CommandArgumentParser], None] | None = None
     custom_parser: ArgParserProtocol | None = None
     custom_help: Callable[[], str | None] | None = None
+    custom_tldr: Callable[[], str | None] | None = None
+    custom_usage: Callable[[], str | None] | None = None
     auto_args: bool = True
     arg_metadata: dict[str, str | dict[str, Any]] = Field(default_factory=dict)
     simple_help_signature: bool = False
+    ignore_in_history: bool = False
+    program: str | None = None
 
     _context: ExecutionContext | None = PrivateAttr(default=None)
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
-    async def parse_args(
+    async def resolve_args(
-        self, raw_args: list[str] | str, from_validate: bool = False
+        self,
-    ) -> tuple[tuple, dict]:
+        raw_args: list[str] | str,
-        if callable(self.custom_parser):
+        from_validate: bool = False,
+        invocation_context: InvocationContext | None = None,
+    ) -> tuple[tuple, dict, dict]:
+        """Parse CLI arguments into execution-ready components.
+
+        This method delegates argument parsing to the configured
+        CommandArgumentParser (if present) and normalizes the result into three
+        distinct groups used during execution:
+
+        - positional arguments (`args`)
+        - keyword arguments (`kwargs`)
+        - execution arguments (`execution_args`)
+
+        Execution arguments represent runtime configuration (e.g. retries,
+        confirmation flags, summary output) and are handled separately from the
+        action's business logic inputs.
+
+        Behavior:
+        - If an argument parser is defined, uses `CommandArgumentParser.parse_args_split()`
+        to resolve and type-coerce all inputs.
+        - If no parser is defined, returns empty args and kwargs.
+        - Supports validation mode (`from_validate=True`) for interactive input,
+        deferring certain errors and resolver execution where applicable.
+        - Handles help/preview signals raised during parsing.
+
+        Args:
+            args (list[str] | str | None): CLI-style argument tokens or a single string.
+            from_validate (bool): Whether parsing is occurring in validation mode
+                (e.g. prompt_toolkit validator). When True, may suppress eager
+                resolution or defer certain errors.
+
+        Returns:
+            tuple:
+                - tuple[Any, ...]: Positional arguments for execution.
+                - dict[str, Any]: Keyword arguments for execution.
+                - dict[str, Any]: Execution-specific arguments (e.g. retries,
+                confirm flags, summary).
+
+        Raises:
+            CommandArgumentError: If argument parsing or validation fails.
+            HelpSignal: If help or TLDR output is triggered during parsing.
+
+        Notes:
+            - Execution arguments are not passed to the underlying Action.
+            - This method is the canonical boundary between CLI parsing and
+            execution semantics.
+        """
+        if self.custom_parser is not None:
+            if not callable(self.custom_parser):
+                raise NotAFalyxError(
+                    "custom_parser must be a callable that implements ArgParserProtocol."
+                )
             if isinstance(raw_args, str):
                 try:
                     raw_args = shlex.split(raw_args)
-                except ValueError:
+                except ValueError as error:
-                    logger.warning(
+                    raise CommandArgumentError(
-                        "[Command:%s] Failed to split arguments: %s",
+                        f"[{self.key}] Failed to parse arguments: {error}"
-                        self.key,
+                    ) from error
-                        raw_args,
-                    )
-                    return ((), {})
             return self.custom_parser(raw_args)
 
         if isinstance(raw_args, str):
             try:
                 raw_args = shlex.split(raw_args)
-            except ValueError:
+            except ValueError as error:
-                logger.warning(
+                raise CommandArgumentError(
-                    "[Command:%s] Failed to split arguments: %s",
+                    f"[{self.key}] Failed to parse arguments: {error}"
-                    self.key,
+                ) from error
-                    raw_args,
+
+        if self.arg_parser is None:
+            raise NotAFalyxError(
+                "Command has no parser configured. "
+                "Provide a custom_parser or CommandArgumentParser."
             )
-                return ((), {})
         if not isinstance(self.arg_parser, CommandArgumentParser):
-            logger.warning(
+            raise NotAFalyxError(
-                "[Command:%s] No argument parser configured, using default parsing.",
+                "arg_parser must be an instance of CommandArgumentParser"
-                self.key,
             )
-            return ((), {})
+
         return await self.arg_parser.parse_args_split(
-            raw_args, from_validate=from_validate
+            raw_args,
+            from_validate=from_validate,
+            invocation_context=invocation_context,
         )
 
     @field_validator("action", mode="before")
     @classmethod
-    def wrap_callable_as_async(cls, action: Any) -> Any:
+    def _wrap_callable_as_async(cls, action: Any) -> Any:
         if isinstance(action, BaseAction):
             return action
         elif callable(action):
             return ensure_async(action)
         raise TypeError("Action must be a callable or an instance of BaseAction")
 
-    def get_argument_definitions(self) -> list[dict[str, Any]]:
+    def _get_argument_definitions(self) -> list[dict[str, Any]]:
         if self.arguments:
             return self.arguments
         elif callable(self.argument_config) and isinstance(
@@ -239,19 +362,62 @@ class Command(BaseModel):
                 help_text=self.help_text,
                 help_epilog=self.help_epilog,
                 aliases=self.aliases,
+                program=self.program,
+                options_manager=self.options_manager,
             )
-            for arg_def in self.get_argument_definitions():
+            for arg_def in self._get_argument_definitions():
                 self.arg_parser.add_argument(*arg_def.pop("flags"), **arg_def)
 
+        if isinstance(self.arg_parser, CommandArgumentParser) and self.execution_options:
+            self.arg_parser.enable_execution_options(self.execution_options)
+
+        if isinstance(self.arg_parser, CommandArgumentParser):
+            self.arg_parser.set_options_manager(self.options_manager)
+
+        if self.ignore_in_history and isinstance(self.action, BaseAction):
+            self.action.ignore_in_history = True
+
     def _inject_options_manager(self) -> None:
         """Inject the options manager into the action if applicable."""
         if isinstance(self.action, BaseAction):
             self.action.set_options_manager(self.options_manager)
 
     async def __call__(self, *args, **kwargs) -> Any:
-        """
+        """Execute the command's underlying action with lifecycle management.
-        Run the action with full hook lifecycle, timing, error handling,
+
-        confirmation prompts, preview, and spinner integration.
+        This method invokes the bound action (BaseAction or callable) using the
+        provided arguments while applying the full Falyx execution lifecycle.
+
+        Execution Flow:
+        1. Create an ExecutionContext for tracking inputs, results, and timing
+        2. Trigger `before` hooks
+        3. Execute the underlying action
+        4. Trigger `on_success` or `on_error` hooks
+        5. Trigger `after` and `on_teardown` hooks
+        6. Record execution via ExecutionRegistry
+
+        Behavior:
+        - Supports both synchronous and asynchronous actions
+        - Applies retry policies if configured
+        - Integrates with confirmation and execution options via OptionsManager
+        - Propagates exceptions unless recovered by hooks (e.g. retry handlers)
+
+        Args:
+            *args (Any): Positional arguments passed to the action.
+            **kwargs (Any): Keyword arguments passed to the action.
+
+        Returns:
+            Any: Result returned by the underlying action.
+
+        Raises:
+            Exception: Propagates execution errors unless handled by hooks.
+
+        Notes:
+            - This method does not perform argument parsing; inputs are assumed
+            to be pre-processed via `resolve_args`.
+            - Execution options (e.g. retries, confirm) are applied externally
+            via Falyx in OptionsManager before invocation.
+            - Lifecycle hooks are always executed, even in failure cases.
         """
         self._inject_options_manager()
         combined_args = args + self.args
@@ -267,7 +433,7 @@ class Command(BaseModel):
         if should_prompt_user(confirm=self.confirm, options=self.options_manager):
             if self.preview_before_confirm:
                 await self.preview()
-            if not await confirm_async(self.confirmation_prompt):
+            if not await confirm_async(self._confirmation_prompt):
                 logger.info("[Command:%s] Cancelled by user.", self.key)
                 raise CancelSignal(f"[Command:{self.key}] Cancelled by confirmation.")
 
@@ -275,15 +441,6 @@ class Command(BaseModel):
 
         try:
             await self.hooks.trigger(HookType.BEFORE, context)
-            if self.spinner:
-                with console.status(
-                    self.spinner_message,
-                    spinner=self.spinner_type,
-                    spinner_style=self.spinner_style,
-                    **self.spinner_kwargs,
-                ):
-                    result = await self.action(*combined_args, **combined_kwargs)
-            else:
             result = await self.action(*combined_args, **combined_kwargs)
 
             context.result = result
@@ -305,7 +462,7 @@ class Command(BaseModel):
         return self._context.result if self._context else None
 
     @property
-    def confirmation_prompt(self) -> FormattedText:
+    def _confirmation_prompt(self) -> FormattedText:
         """Generate a styled prompt_toolkit FormattedText confirmation message."""
         if self.confirm_message and self.confirm_message != "Are you sure?":
             return FormattedText([("class:confirm", self.confirm_message)])
@@ -329,37 +486,93 @@ class Command(BaseModel):
 
         return FormattedText(prompt)
 
+    @property
+    def primary_alias(self) -> str:
+        """Get the primary alias for the command, used in help displays."""
+        if self.aliases:
+            return self.aliases[0].lower()
+        return self.key
+
     @property
     def usage(self) -> str:
         """Generate a help string for the command arguments."""
         if not self.arg_parser:
             return "No arguments defined."
 
-        command_keys_text = self.arg_parser.get_command_keys_text(plain_text=True)
+        command_keys_text = self.arg_parser.get_command_keys_text()
-        options_text = self.arg_parser.get_options_text(plain_text=True)
+        options_text = self.arg_parser.get_options_text()
         return f"  {command_keys_text:<20}  {options_text} "
 
     @property
-    def help_signature(self) -> str:
+    def help_signature(
-        """Generate a help signature for the command."""
+        self,
+        invocation_context: InvocationContext | None = None,
+    ) -> tuple[str, str, str]:
+        """Return a formatted help signature for display.
+
+        This property provides the core information used to render command help
+        in both CLI and interactive menu modes.
+
+        The signature consists of:
+        - usage: A formatted usage string (including arguments if defined)
+        - description: A short description of the command
+        - tag: Optional tag or category label (if applicable)
+
+        Behavior:
+        - If a CommandArgumentParser is present, delegates usage generation to
+        the parser (`get_usage()`).
+        - Otherwise, constructs a minimal usage string from the command key.
+        - Honors `simple_help_signature` to produce a condensed representation
+        (e.g. omitting argument details).
+        - Applies styling appropriate for Rich rendering.
+
+        Returns:
+            tuple:
+                - str: Usage string (e.g. "falyx D | deploy [--help] region")
+                - str: Command description
+                - str: Optional tag/category label
+
+        Notes:
+            - This is the primary interface used by help menus, CLI help output,
+            and command listings.
+            - Formatting may vary depending on CLI vs menu mode.
+        """
         if self.arg_parser and not self.simple_help_signature:
-            signature = [self.arg_parser.get_usage()]
+            usage = self.arg_parser.get_usage(invocation_context)
-            signature.append(f"  {self.help_text or self.description}")
+            description = f"[dim]{self.help_text or self.description}[/dim]"
             if self.tags:
-                signature.append(f"  [dim]Tags: {', '.join(self.tags)}[/dim]")
+                tags = f"[dim]Tags: {', '.join(self.tags)}[/dim]"
-            return "\n".join(signature).strip()
+            else:
+                tags = ""
+            return usage, description, tags
 
         command_keys = " | ".join(
             [f"[{self.style}]{self.key}[/{self.style}]"]
             + [f"[{self.style}]{alias}[/{self.style}]" for alias in self.aliases]
         )
-        return f"{command_keys}  {self.description}"
+        return (
+            f"{command_keys}",
+            f"[dim]{self.help_text or self.description}[/dim]",
+            "",
+        )
 
     def log_summary(self) -> None:
         if self._context:
             self._context.log_summary()
 
-    def show_help(self) -> bool:
+    def render_usage(self, invocation_context: InvocationContext | None = None) -> None:
+        """Render the usage information for the command."""
+        if callable(self.custom_usage):
+            output = self.custom_usage()
+            if output:
+                console.print(output)
+            return
+        if isinstance(self.arg_parser, CommandArgumentParser):
+            self.arg_parser.render_usage(invocation_context)
+        else:
+            console.print(f"[bold]usage:[/] {self.key}")
+
+    def render_help(self, invocation_context: InvocationContext | None = None) -> bool:
         """Display the help message for the command."""
         if callable(self.custom_help):
             output = self.custom_help()
@@ -367,7 +580,19 @@ class Command(BaseModel):
                 console.print(output)
             return True
         if isinstance(self.arg_parser, CommandArgumentParser):
-            self.arg_parser.render_help()
+            self.arg_parser.render_help(invocation_context)
+            return True
+        return False
+
+    def render_tldr(self, invocation_context: InvocationContext | None = None) -> bool:
+        """Display the TLDR message for the command."""
+        if callable(self.custom_tldr):
+            output = self.custom_tldr()
+            if output:
+                console.print(output)
+            return True
+        if isinstance(self.arg_parser, CommandArgumentParser):
+            self.arg_parser.render_tldr(invocation_context)
             return True
         return False
 
@@ -401,3 +626,232 @@ class Command(BaseModel):
             f"Command(key='{self.key}', description='{self.description}' "
             f"action='{self.action}')"
         )
+
+    @classmethod
+    def build(
+        cls,
+        key: str,
+        description: str,
+        action: BaseAction | Callable[..., Any],
+        *,
+        args: tuple = (),
+        kwargs: dict[str, Any] | None = None,
+        hidden: bool = False,
+        aliases: list[str] | None = None,
+        help_text: str = "",
+        help_epilog: str = "",
+        style: Style | str = OneColors.WHITE,
+        confirm: bool = False,
+        confirm_message: str = "Are you sure?",
+        preview_before_confirm: bool = True,
+        spinner: bool = False,
+        spinner_message: str = "Processing...",
+        spinner_type: str = "dots",
+        spinner_style: Style | str = OneColors.CYAN,
+        spinner_speed: float = 1.0,
+        options_manager: OptionsManager | None = None,
+        hooks: HookManager | None = None,
+        before_hooks: list[Callable] | None = None,
+        success_hooks: list[Callable] | None = None,
+        error_hooks: list[Callable] | None = None,
+        after_hooks: list[Callable] | None = None,
+        teardown_hooks: list[Callable] | None = None,
+        tags: list[str] | None = None,
+        logging_hooks: bool = False,
+        retry: bool = False,
+        retry_all: bool = False,
+        retry_policy: RetryPolicy | None = None,
+        arg_parser: CommandArgumentParser | None = None,
+        arguments: list[dict[str, Any]] | None = None,
+        argument_config: Callable[[CommandArgumentParser], None] | None = None,
+        execution_options: list[ExecutionOption | str] | None = None,
+        custom_parser: ArgParserProtocol | None = None,
+        custom_help: Callable[[], str | None] | None = None,
+        custom_tldr: Callable[[], str | None] | None = None,
+        custom_usage: Callable[[], str | None] | None = None,
+        auto_args: bool = True,
+        arg_metadata: dict[str, str | dict[str, Any]] | None = None,
+        simple_help_signature: bool = False,
+        ignore_in_history: bool = False,
+        program: str | None = None,
+    ) -> Command:
+        """Build and configure a `Command` instance from high-level constructor inputs.
+
+        This factory centralizes command construction so callers such as `Falyx` and
+        `CommandRunner` can create fully configured commands through one consistent
+        path. It normalizes optional inputs, validates selected objects, converts
+        execution options into their canonical internal form, and registers any
+        requested command-level hooks.
+
+        In addition to instantiating the `Command`, this method can:
+            - validate and attach an explicit `CommandArgumentParser`
+            - normalize execution options into a `frozenset[ExecutionOption]`
+            - ensure a shared `OptionsManager` is available
+            - attach a custom `HookManager`
+            - register lifecycle hooks for the command
+            - register spinner hooks when spinner support is enabled
+
+        Args:
+            key (str): Primary identifier used to invoke the command.
+            description (str): Short description of the command.
+            action (BaseAction | Callable[..., Any]): Underlying execution logic for
+                the command.
+            args (tuple): Static positional arguments applied to every execution.
+            kwargs (dict[str, Any] | None): Static keyword arguments applied to every
+                execution.
+            hidden (bool): Whether the command should be hidden from menu displays.
+            aliases (list[str] | None): Optional alternate names for invocation.
+            help_text (str): Help text shown in command help output.
+            help_epilog (str): Additional help text shown after the main help body.
+            style (Style | str): Rich style used when rendering the command.
+            confirm (bool): Whether confirmation is required before execution.
+            confirm_message (str): Confirmation prompt text.
+            preview_before_confirm (bool): Whether to preview before confirmation.
+            spinner (bool): Whether to enable spinner lifecycle hooks.
+            spinner_message (str): Spinner message text.
+            spinner_type (str): Spinner animation type.
+            spinner_style (Style | str): Spinner style.
+            spinner_speed (float): Spinner speed multiplier.
+            options_manager (OptionsManager | None): Shared options manager for the
+                command and its parser.
+            hooks (HookManager | None): Optional hook manager to assign directly to the
+                command.
+            before_hooks (list[Callable] | None): Hooks registered for the `BEFORE`
+                lifecycle stage.
+            success_hooks (list[Callable] | None): Hooks registered for the
+                `ON_SUCCESS` lifecycle stage.
+            error_hooks (list[Callable] | None): Hooks registered for the `ON_ERROR`
+                lifecycle stage.
+            after_hooks (list[Callable] | None): Hooks registered for the `AFTER`
+                lifecycle stage.
+            teardown_hooks (list[Callable] | None): Hooks registered for the
+                `ON_TEARDOWN` lifecycle stage.
+            tags (list[str] | None): Optional tags used for grouping and filtering.
+            logging_hooks (bool): Whether to enable debug hook logging.
+            retry (bool): Whether retry behavior is enabled.
+            retry_all (bool): Whether retry behavior should be applied recursively.
+            retry_policy (RetryPolicy | None): Retry configuration for the command.
+            arg_parser (CommandArgumentParser | None): Optional explicit argument
+                parser instance.
+            arguments (list[dict[str, Any]] | None): Declarative argument
+                definitions for the command parser.
+            argument_config (Callable[[CommandArgumentParser], None] | None): Callback
+                used to configure the argument parser.
+            execution_options (list[ExecutionOption | str] | None): Execution-level
+                options to enable for the command.
+            custom_parser (ArgParserProtocol | None): Optional custom parser
+                implementation that overrides normal parser behavior.
+            custom_help (Callable[[], str | None] | None): Optional custom help
+                renderer.
+            custom_tldr (Callable[[], str | None] | None): Optional custom TLDR
+                renderer.
+            custom_usage (Callable[[], str | None] | None): Optional custom usage
+                renderer.
+            auto_args (bool): Whether to infer arguments automatically from the action
+                signature when explicit definitions are not provided.
+            arg_metadata (dict[str, str | dict[str, Any]] | None): Optional metadata
+                used during argument inference.
+            simple_help_signature (bool): Whether to use a simplified help signature.
+            ignore_in_history (bool): Whether to exclude the command from execution
+                history tracking.
+            program (str | None): Parent program name used in help rendering.
+
+        Returns:
+            Command: A fully configured `Command` instance.
+
+        Raises:
+            NotAFalyxError: If `arg_parser` is provided but is not a
+                `CommandArgumentParser` instance.
+            InvalidHookError: If `hooks` is provided but is not a `HookManager` instance.
+
+        Notes:
+            - Execution options supplied as strings are converted to
+            `ExecutionOption` enum values before the command is created.
+            - If no `options_manager` is provided, a new `OptionsManager` is created.
+            - Spinner hooks are registered at build time when `spinner=True`.
+            - This method is the canonical command-construction path used by higher-
+            level APIs such as `Falyx.add_command()` and `CommandRunner.build()`.
+        """
+        if arg_parser and not isinstance(arg_parser, CommandArgumentParser):
+            raise NotAFalyxError(
+                "arg_parser must be an instance of CommandArgumentParser."
+            )
+        arg_parser = arg_parser
+
+        if options_manager and not isinstance(options_manager, OptionsManager):
+            raise NotAFalyxError("options_manager must be an instance of OptionsManager.")
+        options_manager = options_manager or OptionsManager()
+
+        if hooks and not isinstance(hooks, HookManager):
+            raise InvalidHookError("hooks must be an instance of HookManager.")
+        hooks = hooks or HookManager()
+
+        if retry_policy and not isinstance(retry_policy, RetryPolicy):
+            raise NotAFalyxError("retry_policy must be an instance of RetryPolicy.")
+        retry_policy = retry_policy or RetryPolicy()
+
+        if execution_options:
+            parsed_execution_options = frozenset(
+                ExecutionOption(option) if isinstance(option, str) else option
+                for option in execution_options
+            )
+        else:
+            parsed_execution_options = frozenset()
+
+        command = Command(
+            key=key,
+            description=description,
+            action=action,
+            args=args,
+            kwargs=kwargs if kwargs else {},
+            hidden=hidden,
+            aliases=aliases if aliases else [],
+            help_text=help_text,
+            help_epilog=help_epilog,
+            style=style,
+            confirm=confirm,
+            confirm_message=confirm_message,
+            preview_before_confirm=preview_before_confirm,
+            spinner=spinner,
+            spinner_message=spinner_message,
+            spinner_type=spinner_type,
+            spinner_style=spinner_style,
+            spinner_speed=spinner_speed,
+            tags=tags if tags else [],
+            logging_hooks=logging_hooks,
+            hooks=hooks,
+            retry=retry,
+            retry_all=retry_all,
+            retry_policy=retry_policy,
+            options_manager=options_manager,
+            arg_parser=arg_parser,
+            execution_options=parsed_execution_options,
+            arguments=arguments or [],
+            argument_config=argument_config,
+            custom_parser=custom_parser,
+            custom_help=custom_help,
+            custom_tldr=custom_tldr,
+            custom_usage=custom_usage,
+            auto_args=auto_args,
+            arg_metadata=arg_metadata or {},
+            simple_help_signature=simple_help_signature,
+            ignore_in_history=ignore_in_history,
+            program=program,
+        )
+
+        for hook in before_hooks or []:
+            command.hooks.register(HookType.BEFORE, hook)
+        for hook in success_hooks or []:
+            command.hooks.register(HookType.ON_SUCCESS, hook)
+        for hook in error_hooks or []:
+            command.hooks.register(HookType.ON_ERROR, hook)
+        for hook in after_hooks or []:
+            command.hooks.register(HookType.AFTER, hook)
+        for hook in teardown_hooks or []:
+            command.hooks.register(HookType.ON_TEARDOWN, hook)
+
+        if spinner:
+            command.hooks.register(HookType.BEFORE, spinner_before_hook)
+            command.hooks.register(HookType.ON_TEARDOWN, spinner_teardown_hook)
+
+        return command

falyx/command_executor.py

@@ -0,0 +1,311 @@
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
+"""Shared command execution engine for the Falyx CLI framework.
+
+This module defines `CommandExecutor`, a low-level execution service responsible
+for running already-resolved `Command` objects with a consistent outer lifecycle.
+
+`CommandExecutor` sits between higher-level orchestration layers (such as
+`Falyx.execute_command()` or `CommandRunner.run()`) and the command itself.
+It does not perform command lookup or argument parsing. Instead, it accepts a
+resolved `Command` plus prepared `args`, `kwargs`, and `execution_args`, then
+applies executor-level behavior around the command invocation.
+
+Responsibilities:
+    - Apply execution-scoped runtime overrides such as confirmation flags
+    - Apply retry overrides from execution arguments
+    - Trigger executor-level lifecycle hooks
+    - Create and manage an outer `ExecutionContext`
+    - Delegate actual invocation to the resolved `Command`
+    - Handle interruption and failure policies
+    - Optionally print execution summaries via `ExecutionRegistry`
+
+Execution Model:
+    1. A command is resolved and its arguments are prepared elsewhere.
+    2. Retry and execution-option overrides are derived from `execution_args`.
+    3. An outer `ExecutionContext` is created for executor-level tracking.
+    4. Executor hooks are triggered around the command invocation.
+    5. The command is executed inside an `OptionsManager.override_namespace()`
+       context for scoped runtime overrides.
+    6. Errors are either surfaced, wrapped, or rendered depending on the
+       configured execution policy.
+    7. Optional summary output is emitted after execution completes.
+
+Design Notes:
+    - `CommandExecutor` is intentionally narrower in scope than `Falyx`.
+      It does not resolve commands, parse raw CLI text, or manage menu state.
+    - `Command` still owns command-local behavior such as confirmation,
+      command hooks, and delegation to the underlying `Action`.
+    - This module exists to centralize shared execution behavior and reduce
+      duplication across Falyx runtime entrypoints.
+
+Typical Usage:
+    executor = CommandExecutor(options=options, hooks=hooks)
+    result = await executor.execute(
+        command=command,
+        args=args,
+        kwargs=kwargs,
+        execution_args=execution_args,
+    )
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from falyx.action import Action
+from falyx.command import Command
+from falyx.context import ExecutionContext
+from falyx.exceptions import FalyxError
+from falyx.execution_registry import ExecutionRegistry as er
+from falyx.hook_manager import HookManager, HookType
+from falyx.logger import logger
+from falyx.options_manager import OptionsManager
+
+
+class CommandExecutor:
+    """Execute resolved Falyx commands with shared outer lifecycle handling.
+
+    `CommandExecutor` provides a reusable execution service for running a
+    `Command` after command resolution and argument parsing have already been
+    completed.
+
+    This class is intended to be shared by higher-level entrypoints such as
+    `Falyx` and `CommandRunner`. It centralizes the outer execution flow so
+    command execution semantics remain consistent across menu-driven and
+    programmatic use cases.
+
+    Responsibilities:
+        - Apply retry overrides from execution arguments
+        - Apply scoped runtime overrides using `OptionsManager`
+        - Trigger executor-level hooks before and after command execution
+        - Create and manage an executor-level `ExecutionContext`
+        - Control whether errors are raised or wrapped
+        - Emit optional execution summaries
+
+    Attributes:
+        options (OptionsManager): Shared options manager used to apply scoped
+            execution overrides.
+        hooks (HookManager): Hook manager for executor-level lifecycle hooks.
+    """
+
+    def __init__(
+        self,
+        *,
+        options: OptionsManager,
+        hooks: HookManager,
+    ) -> None:
+        self.options = options
+        self.hooks = hooks
+
+    def _debug_hooks(self, command: Command) -> None:
+        """Log executor-level and command-level hook registrations for debugging.
+
+        This helper is used to surface the currently registered hooks on both the
+        executor and the resolved command before execution begins.
+
+        Args:
+            command (Command): The command about to be executed.
+        """
+        logger.debug("executor hooks:\n%s", str(self.hooks))
+        logger.debug("['%s'] hooks:\n%s", command.key, str(command.hooks))
+
+    def _apply_retry_overrides(
+        self,
+        command: Command,
+        execution_args: dict[str, Any],
+    ) -> None:
+        """Apply retry-related execution overrides to the command.
+
+        This method inspects execution-level retry options and updates the
+        command's retry policy in place when overrides are provided. If the
+        command's underlying action is an `Action`, the updated retry policy is
+        propagated to that action as well.
+
+        Args:
+            command (Command): The command whose retry policy may be updated.
+            execution_args (dict[str, Any]): Execution-level arguments that may
+                contain retry overrides such as `retries`, `retry_delay`, and
+                `retry_backoff`.
+
+        Notes:
+            - If no retry-related overrides are provided, this method does nothing.
+            - If the command action is not an `Action`, a warning is logged and the
+            command-level retry policy is updated without propagating it further.
+        """
+        retries = execution_args.get("retries", 0)
+        retry_delay = execution_args.get("retry_delay", 0.0)
+        retry_backoff = execution_args.get("retry_backoff", 0.0)
+
+        logger.debug(
+            "[_apply_retry_overrides]: retries=%s, retry_delay=%s, retry_backoff=%s",
+            retries,
+            retry_delay,
+            retry_backoff,
+        )
+        if not retries and not retry_delay and not retry_backoff:
+            return
+
+        command.retry_policy.enabled = True
+        if retries:
+            command.retry_policy.max_retries = retries
+        if retry_delay:
+            command.retry_policy.delay = retry_delay
+        if retry_backoff:
+            command.retry_policy.backoff = retry_backoff
+
+        if isinstance(command.action, Action):
+            command.action.set_retry_policy(command.retry_policy)
+        else:
+            logger.warning(
+                "[%s] Retry requested, but action is not an Action instance.",
+                command.key,
+            )
+
+    def _execution_option_overrides(
+        self,
+        execution_args: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Build scoped option overrides from execution arguments.
+
+        This method extracts execution-only runtime flags that should be applied
+        through the `OptionsManager` during command execution.
+
+        Args:
+            execution_args (dict[str, Any]): Execution-level arguments returned
+                from command argument resolution.
+
+        Returns:
+            dict[str, Any]: Mapping of option names to temporary execution-scoped
+            override values.
+        """
+        return {
+            "force_confirm": execution_args.get("force_confirm", False),
+            "skip_confirm": execution_args.get("skip_confirm", False),
+        }
+
+    async def execute(
+        self,
+        *,
+        command: Command,
+        args: tuple,
+        kwargs: dict[str, Any],
+        execution_args: dict[str, Any],
+        raise_on_error: bool = True,
+        wrap_errors: bool = False,
+        summary_last_result: bool = False,
+    ) -> Any:
+        """Execute a resolved command with executor-level lifecycle management.
+
+        This method is the primary entrypoint of `CommandExecutor`. It accepts an
+        already-resolved `Command` and its prepared execution inputs, then applies
+        shared outer execution behavior around the command invocation.
+
+        Execution Flow:
+            1. Log currently registered hooks for debugging.
+            2. Apply retry overrides from `execution_args`.
+            3. Derive scoped runtime overrides for the execution namespace.
+            4. Create and start an outer `ExecutionContext`.
+            5. Trigger executor-level `BEFORE` hooks.
+            6. Execute the command inside an execution-scoped options override
+            context.
+            7. Trigger executor-level `SUCCESS` or `ERROR` hooks.
+            8. Trigger `AFTER` and `ON_TEARDOWN` hooks.
+            9. Optionally print an execution summary.
+
+        Args:
+            command (Command): The resolved command to execute.
+            args (tuple): Positional arguments to pass to the command.
+            kwargs (dict[str, Any]): Keyword arguments to pass to the command.
+            execution_args (dict[str, Any]): Execution-only arguments that affect
+                runtime behavior, such as retry or confirmation overrides.
+            raise_on_error (bool): Whether execution errors should be re-raised
+                after handling.
+            wrap_errors (bool): Whether handled errors should be wrapped in a
+                `FalyxError` before being raised.
+            summary_last_result (bool): Whether summary output should only have the
+                last recorded result when summary reporting is enabled.
+
+        Returns:
+            Any: The result returned by the command, or any recovered result
+            attached to the execution context.
+
+        Raises:
+            KeyboardInterrupt: If execution is interrupted by the user and
+                `raise_on_error` is True and `wrap_errors` is False.
+            EOFError: If execution receives EOF interruption and `raise_on_error`
+                is True and `wrap_errors` is False.
+            FalyxError: If `wrap_errors` is True and execution is interrupted or
+                fails.
+            Exception: Re-raises the underlying execution error when
+                `raise_on_error` is True and `wrap_errors` is False.
+
+        Notes:
+            - This method assumes the command has already been resolved and its
+            arguments have already been parsed.
+            - Command-local behavior, such as confirmation prompts and command hook
+            execution, remains the responsibility of `Command.__call__()`.
+            - Summary output is only emitted when the `summary` execution option is
+            present in `execution_args`.
+        """
+        if not (raise_on_error or wrap_errors):
+            raise FalyxError(
+                "CommandExecutor.execute() requires either raise_on_error=True "
+                "or wrap_errors=True."
+            )
+        self._debug_hooks(command)
+        self._apply_retry_overrides(command, execution_args)
+        overrides = self._execution_option_overrides(execution_args)
+
+        context = ExecutionContext(
+            name=command.description,
+            args=args,
+            kwargs=kwargs,
+            action=command,
+        )
+        logger.info(
+            "[execute] Starting execution of '%s' with args: %s, kwargs: %s",
+            command.description,
+            args,
+            kwargs,
+        )
+        context.start_timer()
+
+        try:
+            await self.hooks.trigger(HookType.BEFORE, context)
+            with self.options.override_namespace(
+                overrides=overrides,
+                namespace_name="execution",
+            ):
+                result = await command(*args, **kwargs)
+            context.result = result
+            await self.hooks.trigger(HookType.ON_SUCCESS, context)
+        except (KeyboardInterrupt, EOFError) as error:
+            logger.info(
+                "[execute] '%s' interrupted by user.",
+                command.key,
+            )
+            if wrap_errors:
+                raise FalyxError(
+                    f"[execute] '{command.key}' interrupted by user."
+                ) from error
+            raise error
+        except Exception as error:
+            logger.debug(
+                "[execute] '%s' failed: %s",
+                command.key,
+                error,
+                exc_info=True,
+            )
+            context.exception = error
+            await self.hooks.trigger(HookType.ON_ERROR, context)
+            if wrap_errors:
+                raise FalyxError(f"[execute] '{command.key}' failed: {error}") from error
+            raise error
+        finally:
+            context.stop_timer()
+            await self.hooks.trigger(HookType.AFTER, context)
+            await self.hooks.trigger(HookType.ON_TEARDOWN, context)
+        if execution_args.get("summary") and summary_last_result:
+            er.summary(last_result=True)
+        elif execution_args.get("summary"):
+            er.summary()
+        return context.result

falyx/command_runner.py

@@ -0,0 +1,531 @@
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
+"""Standalone command runner for the Falyx CLI framework.
+
+This module defines `CommandRunner`, a developer-facing convenience wrapper for
+executing a single `Command` outside the full `Falyx` runtime.
+
+`CommandRunner` is designed for programmatic and standalone command execution
+where command lookup, menu interaction, and root CLI parsing are not needed.
+It provides a small, focused API that:
+
+- owns a single `Command`
+- ensures the command and parser share a consistent `OptionsManager`
+- delegates shared execution behavior to `CommandExecutor`
+- supports both wrapping an existing `Command` and building one from raw
+  constructor-style arguments
+
+Responsibilities:
+    - Hold a single resolved `Command` for repeated execution
+    - Normalize runtime dependencies such as `OptionsManager`, `HookManager`,
+      and `Console`
+    - Resolve command arguments from raw argv-style input
+    - Delegate execution to `CommandExecutor` for shared outer lifecycle
+      handling
+
+Design Notes:
+    - `CommandRunner` is intentionally narrower than `Falyx`.
+      It does not resolve commands by name, render menus, or manage built-ins.
+    - `CommandExecutor` remains the shared execution core.
+      `CommandRunner` exists as a convenience layer for developer-facing and
+      standalone use cases.
+    - `Command` still owns command-local behavior such as confirmation,
+      command hook execution, and delegation to the underlying `Action`.
+
+Typical Usage:
+    runner = CommandRunner.from_command(existing_command)
+    result = await runner.run(["--region", "us-east"])
+
+    #!/usr/bin/env python
+    import asyncio
+    runner = CommandRunner.build(
+        key="D",
+        description="Deploy",
+        action=deploy,
+    )
+    result = asyncio.run(runner.cli())
+    $ ./deploy.py --region us-east
+"""
+from __future__ import annotations
+
+import asyncio
+import sys
+from typing import Any, Callable
+
+from rich.console import Console
+
+from falyx.action import BaseAction
+from falyx.command import Command
+from falyx.command_executor import CommandExecutor
+from falyx.console import console as falyx_console
+from falyx.console import error_console, print_error
+from falyx.exceptions import (
+    CommandArgumentError,
+    FalyxError,
+    InvalidHookError,
+    NotAFalyxError,
+)
+from falyx.execution_option import ExecutionOption
+from falyx.hook_manager import HookManager
+from falyx.logger import logger
+from falyx.options_manager import OptionsManager
+from falyx.parser.command_argument_parser import CommandArgumentParser
+from falyx.protocols import ArgParserProtocol
+from falyx.retry import RetryPolicy
+from falyx.signals import BackSignal, CancelSignal, HelpSignal, QuitSignal
+from falyx.themes import OneColors
+
+
+class CommandRunner:
+    """Run a single Falyx command outside the full Falyx application runtime.
+
+    `CommandRunner` is a lightweight wrapper around a single `Command` plus a
+    `CommandExecutor`. It is intended for standalone execution, testing, and
+    developer-facing programmatic usage where command resolution has already
+    happened or is unnecessary.
+
+    This class is responsible for:
+        - storing the bound `Command`
+        - providing a shared `OptionsManager` to the command and its parser
+        - exposing a simple `run()` method that accepts argv-style input
+        - delegating shared execution behavior to `CommandExecutor`
+
+    Attributes:
+        command (Command): The command executed by this runner.
+        program (str): Program name used in CLI usage text and help output.
+        options (OptionsManager): Shared options manager used by the command,
+            parser, and executor.
+        runner_hooks (HookManager): Executor-level hooks used during execution.
+        console (Console): Rich console used for user-facing output.
+        executor (CommandExecutor): Shared execution engine used to run the
+            bound command.
+    """
+
+    def __init__(
+        self,
+        command: Command,
+        *,
+        program: str | None = None,
+        options: OptionsManager | None = None,
+        runner_hooks: HookManager | None = None,
+        console: Console | None = None,
+    ) -> None:
+        """Initialize a `CommandRunner` for a single command.
+
+        The runner ensures that the bound command, its argument parser, and the
+        internal `CommandExecutor` all share the same `OptionsManager` and runtime
+        dependencies.
+
+        Args:
+            command (Command): The command to execute.
+            program (str | None): Program name used in CLI usage text, invocation-path
+                rendering, and built-in help output. If `None`, an empty program name is
+                used.
+            options (OptionsManager | None): Optional shared options manager. If
+                omitted, a new `OptionsManager` is created.
+            runner_hooks (HookManager | None): Optional executor-level hook manager. If
+                omitted, a new `HookManager` is created.
+            console (Console | None): Optional Rich console for output. If omitted,
+                the default Falyx console is used.
+        """
+        self.command = command
+        self.program = program or ""
+        self.options = self._get_options(options)
+        self.runner_hooks = self._get_hooks(runner_hooks)
+        self.console = self._get_console(console)
+        self.error_console = error_console
+        self.command.options_manager = self.options
+        if program:
+            self.command.program = program
+        if isinstance(self.command.arg_parser, CommandArgumentParser):
+            self.command.arg_parser.set_options_manager(self.options)
+            self.command.arg_parser.is_runner_mode = True
+            if program:
+                self.command.arg_parser.program = program
+        self.executor = CommandExecutor(
+            options=self.options,
+            hooks=self.runner_hooks,
+        )
+        self.options.from_mapping(values={}, namespace_name="execution")
+
+    def _get_console(self, console) -> Console:
+        if console is None:
+            return falyx_console
+        elif isinstance(console, Console):
+            return console
+        else:
+            raise NotAFalyxError("console must be an instance of rich.Console or None.")
+
+    def _get_options(self, options) -> OptionsManager:
+        if options is None:
+            return OptionsManager()
+        elif isinstance(options, OptionsManager):
+            return options
+        else:
+            raise NotAFalyxError("options must be an instance of OptionsManager or None.")
+
+    def _get_hooks(self, hooks) -> HookManager:
+        if hooks is None:
+            return HookManager()
+        elif isinstance(hooks, HookManager):
+            return hooks
+        else:
+            raise InvalidHookError("hooks must be an instance of HookManager or None.")
+
+    async def run(
+        self,
+        argv: list[str] | str | None = None,
+        raise_on_error: bool = True,
+        wrap_errors: bool = False,
+        summary_last_result: bool = False,
+    ) -> Any:
+        """Resolve arguments and execute the bound command.
+
+        This method is the primary execution entrypoint for `CommandRunner`. It
+        accepts raw argv-style tokens, resolves them into positional arguments,
+        keyword arguments, and execution arguments via `Command.resolve_args()`,
+        then delegates execution to the internal `CommandExecutor`.
+
+        Args:
+            argv (list[str] | str | None): Optional argv-style argument tokens or
+                string (uses `shlex.split()` if a string is provided). If omitted,
+                `sys.argv[1:]` is used.
+
+        Returns:
+            Any: The result returned by the bound command.
+
+        Raises:
+            Exception: Propagates any execution error surfaced by the underlying
+                `CommandExecutor` or command execution path.
+        """
+        argv = sys.argv[1:] if argv is None else argv
+        args, kwargs, execution_args = await self.command.resolve_args(argv)
+        logger.debug(
+            "Executing command '%s' with args=%s, kwargs=%s, execution_args=%s",
+            self.command.description,
+            args,
+            kwargs,
+            execution_args,
+        )
+        return await self.executor.execute(
+            command=self.command,
+            args=args,
+            kwargs=kwargs,
+            execution_args=execution_args,
+            raise_on_error=raise_on_error,
+            wrap_errors=wrap_errors,
+            summary_last_result=summary_last_result,
+        )
+
+    async def cli(
+        self,
+        argv: list[str] | str | None = None,
+        summary_last_result: bool = False,
+    ) -> Any:
+        """Run the bound command as a shell-oriented CLI entrypoint.
+
+        This method wraps `run()` with command-line specific behavior. It executes the
+        bound command using raw argv-style input, then translates framework signals and
+        execution failures into user-facing console output and process exit codes.
+
+        Unlike `run()`, this method is intended for direct CLI usage rather than
+        programmatic integration. It may terminate the current process via `sys.exit()`.
+
+        Behavior:
+            - Delegates normal execution to `run()`
+            - Exits with status code `0` when help output is requested
+            - Exits with status code `2` for command argument or usage errors
+            - Exits with status code `1` for execution failures and non-success control
+            flow such as cancellation or back-navigation
+            - Exits with status code `130` for quit/interrupt-style termination
+
+        Args:
+            argv (list[str] | str | None): Optional argv-style argument tokens or string
+                (uses `shlex.split()` if a string is provided). If omitted, `sys.argv[1:]`
+                is used by `run()`.
+            summary_last_result (bool): Whether summary output should include the last
+                recorded result when summary reporting is enabled.
+
+        Returns:
+            Any: The result returned by the bound command when execution completes
+            successfully.
+
+        Raises:
+            SystemExit: Always raised for handled CLI exit paths, including help,
+                argument errors, cancellations, and execution failures.
+
+        Notes:
+            - This method is intentionally shell-facing and should be used in
+            script entrypoints such as `asyncio.run(runner.cli())`.
+            - For programmatic use, prefer `run()`, which preserves normal Python
+            exception behavior and does not call `sys.exit()`.
+        """
+        try:
+            return await self.run(
+                argv=argv,
+                raise_on_error=False,
+                wrap_errors=True,
+                summary_last_result=summary_last_result,
+            )
+        except HelpSignal:
+            sys.exit(0)
+        except CommandArgumentError as error:
+            self.command.render_help()
+            print_error(message=error)
+            sys.exit(2)
+        except FalyxError as error:
+            print_error(message=error)
+            sys.exit(1)
+        except QuitSignal:
+            logger.info("[QuitSignal]. <- Exiting run.")
+            sys.exit(130)
+        except BackSignal:
+            logger.info("[BackSignal]. <- Exiting run.")
+            sys.exit(1)
+        except CancelSignal:
+            logger.info("[CancelSignal]. <- Exiting run.")
+            sys.exit(1)
+        except asyncio.CancelledError:
+            logger.info("[asyncio.CancelledError]. <- Exiting run.")
+            sys.exit(1)
+
+    @classmethod
+    def from_command(
+        cls,
+        command: Command,
+        *,
+        program: str | None = None,
+        runner_hooks: HookManager | None = None,
+        options: OptionsManager | None = None,
+        console: Console | None = None,
+    ) -> CommandRunner:
+        """Create a `CommandRunner` from an existing `Command` instance.
+
+        This factory is useful when a command has already been defined elsewhere
+        and should be exposed through the standalone runner interface without
+        rebuilding it.
+
+        Args:
+            command (Command): Existing command instance to wrap.
+            program (str | None): Program name used in CLI usage text, invocation-path
+                rendering, and built-in help output. If `None`, an empty program name is
+                used.
+            runner_hooks (HookManager | None): Optional executor-level hook manager
+                for the runner.
+            options (OptionsManager | None): Optional shared options manager.
+            console (Console | None): Optional Rich console for output.
+
+        Returns:
+            CommandRunner: A runner bound to the provided command.
+
+        Raises:
+            NotAFalyxError: If `runner_hooks` is provided but is not a
+                `HookManager` instance.
+        """
+        if not isinstance(command, Command):
+            raise NotAFalyxError("command must be an instance of Command.")
+        if runner_hooks and not isinstance(runner_hooks, HookManager):
+            raise InvalidHookError("runner_hooks must be an instance of HookManager.")
+        return cls(
+            command=command,
+            program=program,
+            options=options,
+            runner_hooks=runner_hooks,
+            console=console,
+        )
+
+    @classmethod
+    def build(
+        cls,
+        key: str,
+        description: str,
+        action: BaseAction | Callable[..., Any],
+        *,
+        program: str | None = None,
+        runner_hooks: HookManager | None = None,
+        args: tuple = (),
+        kwargs: dict[str, Any] | None = None,
+        hidden: bool = False,
+        aliases: list[str] | None = None,
+        help_text: str = "",
+        help_epilog: str = "",
+        style: str = OneColors.WHITE,
+        confirm: bool = False,
+        confirm_message: str = "Are you sure?",
+        preview_before_confirm: bool = True,
+        spinner: bool = False,
+        spinner_message: str = "Processing...",
+        spinner_type: str = "dots",
+        spinner_style: str = OneColors.CYAN,
+        spinner_speed: float = 1.0,
+        options: OptionsManager | None = None,
+        command_hooks: HookManager | None = None,
+        before_hooks: list[Callable] | None = None,
+        success_hooks: list[Callable] | None = None,
+        error_hooks: list[Callable] | None = None,
+        after_hooks: list[Callable] | None = None,
+        teardown_hooks: list[Callable] | None = None,
+        tags: list[str] | None = None,
+        logging_hooks: bool = False,
+        retry: bool = False,
+        retry_all: bool = False,
+        retry_policy: RetryPolicy | None = None,
+        arg_parser: CommandArgumentParser | None = None,
+        arguments: list[dict[str, Any]] | None = None,
+        argument_config: Callable[[CommandArgumentParser], None] | None = None,
+        execution_options: list[ExecutionOption | str] | None = None,
+        custom_parser: ArgParserProtocol | None = None,
+        custom_help: Callable[[], str | None] | None = None,
+        custom_tldr: Callable[[], str | None] | None = None,
+        custom_usage: Callable[[], str | None] | None = None,
+        auto_args: bool = True,
+        arg_metadata: dict[str, str | dict[str, Any]] | None = None,
+        simple_help_signature: bool = False,
+        ignore_in_history: bool = False,
+        console: Console | None = None,
+    ) -> CommandRunner:
+        """Build a `Command` and wrap it in a `CommandRunner`.
+
+        This factory is a convenience constructor for standalone usage. It mirrors
+        the high-level command-building API by creating a configured `Command`
+        through `Command.build()` and then returning a `CommandRunner` bound to it.
+
+        Args:
+            key (str): Primary key used to invoke the command.
+            description (str): Short description of the command.
+            action (BaseAction | Callable[..., Any]): Underlying execution logic for
+                the command.
+            program (str | None): Program name used in CLI usage text, invocation-path
+                rendering, and built-in help output. If `None`, an empty program name is
+                used.
+            runner_hooks (HookManager | None): Optional executor-level hooks for the
+                runner.
+            args (tuple): Static positional arguments applied to the command.
+            kwargs (dict[str, Any] | None): Static keyword arguments applied to the
+                command.
+            hidden (bool): Whether the command should be hidden from menu displays.
+            aliases (list[str] | None): Optional alternate invocation names.
+            help_text (str): Help text shown in command help output.
+            help_epilog (str): Additional help text shown after the main help body.
+            style (str): Rich style used for rendering the command.
+            confirm (bool): Whether confirmation is required before execution.
+            confirm_message (str): Confirmation prompt text.
+            preview_before_confirm (bool): Whether to preview before confirmation.
+            spinner (bool): Whether to enable spinner integration.
+            spinner_message (str): Spinner message text.
+            spinner_type (str): Spinner animation type.
+            spinner_style (str): Spinner style.
+            spinner_speed (float): Spinner speed multiplier.
+            options (OptionsManager | None): Shared options manager for the command
+                and runner.
+            command_hooks (HookManager | None): Optional hook manager for the built
+                command itself.
+            before_hooks (list[Callable] | None): Command hooks registered for the
+                `BEFORE` lifecycle stage.
+            success_hooks (list[Callable] | None): Command hooks registered for the
+                `ON_SUCCESS` lifecycle stage.
+            error_hooks (list[Callable] | None): Command hooks registered for the
+                `ON_ERROR` lifecycle stage.
+            after_hooks (list[Callable] | None): Command hooks registered for the
+                `AFTER` lifecycle stage.
+            teardown_hooks (list[Callable] | None): Command hooks registered for the
+                `ON_TEARDOWN` lifecycle stage.
+            tags (list[str] | None): Optional tags used for grouping and filtering.
+            logging_hooks (bool): Whether to enable debug hook logging.
+            retry (bool): Whether retry behavior is enabled.
+            retry_all (bool): Whether retry behavior should be applied recursively.
+            retry_policy (RetryPolicy | None): Retry configuration for the command.
+            arg_parser (CommandArgumentParser | None): Optional explicit argument
+                parser instance.
+            arguments (list[dict[str, Any]] | None): Declarative argument
+                definitions.
+            argument_config (Callable[[CommandArgumentParser], None] | None):
+                Callback used to configure the argument parser.
+            execution_options (list[ExecutionOption | str] | None): Execution-level
+                options to enable for the command.
+            custom_parser (ArgParserProtocol | None): Optional custom parser
+                implementation.
+            custom_help (Callable[[], str | None] | None): Optional custom help
+                renderer.
+            custom_tldr (Callable[[], str | None] | None): Optional custom TLDR
+                renderer.
+            custom_usage (Callable[[], str | None] | None): Optional custom usage
+                renderer.
+            auto_args (bool): Whether to infer arguments automatically from the
+                action signature.
+            arg_metadata (dict[str, str | dict[str, Any]] | None): Optional
+                metadata used during argument inference.
+            simple_help_signature (bool): Whether to use a simplified help
+                signature.
+            ignore_in_history (bool): Whether to exclude the command from execution
+                history tracking.
+            console (Console | None): Optional Rich console for output.
+
+        Returns:
+            CommandRunner: A runner wrapping the newly built command.
+
+        Raises:
+            NotAFalyxError: If `arg_parser` is provided but is not a
+                `CommandArgumentParser` instance.
+            InvalidHookError: If `runner_hooks` is provided but is not a `HookManager`
+
+        Notes:
+            - This method is intended as a standalone convenience factory.
+            - Command construction is delegated to `Command.build()` so command
+            configuration remains centralized.
+        """
+        options = options or OptionsManager()
+        command = Command.build(
+            key=key,
+            description=description,
+            action=action,
+            program=program,
+            args=args,
+            kwargs=kwargs,
+            hidden=hidden,
+            aliases=aliases,
+            help_text=help_text,
+            help_epilog=help_epilog,
+            style=style,
+            confirm=confirm,
+            confirm_message=confirm_message,
+            preview_before_confirm=preview_before_confirm,
+            spinner=spinner,
+            spinner_message=spinner_message,
+            spinner_type=spinner_type,
+            spinner_style=spinner_style,
+            spinner_speed=spinner_speed,
+            tags=tags,
+            logging_hooks=logging_hooks,
+            retry=retry,
+            retry_all=retry_all,
+            retry_policy=retry_policy,
+            options_manager=options,
+            hooks=command_hooks,
+            before_hooks=before_hooks,
+            success_hooks=success_hooks,
+            error_hooks=error_hooks,
+            after_hooks=after_hooks,
+            teardown_hooks=teardown_hooks,
+            arg_parser=arg_parser,
+            execution_options=execution_options,
+            arguments=arguments,
+            argument_config=argument_config,
+            custom_parser=custom_parser,
+            custom_help=custom_help,
+            custom_tldr=custom_tldr,
+            custom_usage=custom_usage,
+            auto_args=auto_args,
+            arg_metadata=arg_metadata,
+            simple_help_signature=simple_help_signature,
+            ignore_in_history=ignore_in_history,
+        )
+
+        if runner_hooks and not isinstance(runner_hooks, HookManager):
+            raise InvalidHookError("runner_hooks must be an instance of HookManager.")
+
+        return cls(
+            command=command,
+            options=options,
+            runner_hooks=runner_hooks,
+            console=console,
+        )

falyx/completer.py

@@ -1,5 +1,37 @@
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
+"""Prompt Toolkit completion support for routed Falyx command input.
+
+This module defines `FalyxCompleter`, the interactive completion layer used by
+Falyx menu and prompt-driven CLI sessions. The completer is routing-aware: it
+delegates namespace traversal to `Falyx.resolve_completion_route()` and only
+hands control to a command's `CommandArgumentParser` after a leaf command has
+been identified.
+
+Completion behavior is split into two phases:
+
+1. Namespace completion
+   While the user is still selecting a command or namespace entry, completion
+   candidates are derived from the active namespace via
+   `completion_names`. Namespace-level help flags such as `-h`, `--help`,
+   `-T`, and `--tldr` are also suggested when appropriate.
+
+2. Leaf-command completion
+   Once routing reaches a concrete command, the remaining argv fragment is
+   delegated to `CommandArgumentParser.suggest_next()` so command-specific
+   flags, values, choices, and positional suggestions can be surfaced.
+
+The completer also supports preview-prefixed input such as `?deploy`, preserves
+shell-safe quoting for suggestions containing whitespace, and integrates
+directly with Prompt Toolkit's completion API by yielding `Completion`
+instances.
+
+Typical usage:
+    session = PromptSession(completer=FalyxCompleter(falyx))
+"""
+
 from __future__ import annotations
 
+import os
 import shlex
 from typing import TYPE_CHECKING, Iterable
 
@@ -11,37 +43,215 @@ if TYPE_CHECKING:
 
 
 class FalyxCompleter(Completer):
-    """Completer for Falyx commands."""
+    """Prompt Toolkit completer for routed Falyx input.
 
-    def __init__(self, falyx: "Falyx"):
+    `FalyxCompleter` provides context-aware completions for interactive Falyx
+    sessions. It first asks the owning `Falyx` instance to resolve the current
+    input into a partial completion route. Based on that route, it either:
+
+    - suggests visible entries from the active namespace, or
+    - delegates argument completion to the resolved command's argument parser.
+
+    This keeps completion aligned with Falyx's routing model so nested
+    namespaces, preview-prefixed commands, and command-local argument parsing
+    all behave consistently with actual execution.
+
+    Args:
+        falyx (Falyx): Active Falyx application instance used to resolve routes
+            and retrieve completion candidates.
+    """
+
+    def __init__(self, falyx: Falyx):
+        """Initialize the completer with a bound Falyx instance.
+
+        Args:
+            falyx (Falyx): Active Falyx application that owns the routing and
+                command metadata used for completion.
+        """
         self.falyx = falyx
 
-    def get_completions(self, document: Document, complete_event) -> Iterable[Completion]:
+    def get_completions(self, document: Document, complete_event):
+        """Yield completions for the current input buffer.
+
+        This method is the main Prompt Toolkit completion entrypoint. It parses
+        the text before the cursor, determines whether the user is still routing
+        through namespaces or has already reached a leaf command, and then
+        yields matching `Completion` objects.
+
+        Behavior:
+            - Splits the current input using `shlex.split()`.
+            - Detects preview-mode input prefixed with `?`.
+            - Separates committed tokens from the active stub under the cursor.
+            - Resolves the partial route through `Falyx.resolve_completion_route()`.
+            - Suggests namespace entries and namespace help flags while routing.
+            - Delegates leaf-command completion to
+              `CommandArgumentParser.suggest_next()` once a command is resolved.
+            - Preserves shell-safe quoting for suggestions containing spaces.
+
+        Args:
+            document (Document): Prompt Toolkit document representing the current
+                input buffer and cursor position.
+            complete_event: Prompt Toolkit completion event metadata. It is not
+                currently inspected directly.
+
+        Yields:
+            Completion: Completion candidates appropriate to the current routed
+            input state.
+
+        Notes:
+            - Invalid shell quoting causes completion to stop silently rather
+              than raising.
+            - Command-specific completion is only attempted after a concrete leaf
+              command has been resolved.
+        """
         text = document.text_before_cursor
         try:
             tokens = shlex.split(text)
-            cursor_at_end_of_token = document.text_before_cursor.endswith((" ", "\t"))
+            cursor_at_end = text.endswith((" ", "\t"))
         except ValueError:
             return
 
-        if not tokens or (len(tokens) == 1 and not cursor_at_end_of_token):
+        is_preview = False
-            # Suggest command keys and aliases
+        if tokens and tokens[0].startswith("?"):
-            yield from self._suggest_commands(tokens[0] if tokens else "")
+            is_preview = True
+            tokens[0] = tokens[0][1:]
+
+        if cursor_at_end:
+            committed_tokens = tokens
+            stub = ""
+        else:
+            committed_tokens = tokens[:-1] if tokens else []
+            stub = tokens[-1] if tokens else ""
+
+        context = self.falyx.get_current_invocation_context().model_copy(
+            update={"is_preview": is_preview}
+        )
+
+        route = self.falyx.resolve_completion_route(
+            committed_tokens,
+            stub=stub,
+            cursor_at_end_of_token=cursor_at_end,
+            invocation_context=context,
+            is_preview=is_preview,
+        )
+
+        # Still selecting an entry in the current namespace
+        if route.expecting_entry:
+            suggestions = self._suggest_namespace_entries(route.namespace, route.stub)
+
+            # Only here should namespace-level help/TLDR be suggested.
+            # TODO: better completer in FalyxParser
+            if not route.command:  # and (not route.stub or route.stub.startswith("-")):
+                for flag in route.namespace.parser._options_by_dest:
+                    if flag.startswith(route.stub):
+                        suggestions.append(flag)
+
+            if route.is_preview:
+                suggestions = [f"?{s}" for s in suggestions]
+                current_stub = f"?{route.stub}" if route.stub else "?"
+            else:
+                current_stub = route.stub
+
+            yield from self._yield_lcp_completions(suggestions, current_stub)
             return
 
-    def _suggest_commands(self, prefix: str) -> Iterable[Completion]:
+        # Leaf command: CAP owns the rest
-        prefix = prefix.upper()
+        if not route.command or not route.command.arg_parser:
-        keys = [self.falyx.exit_command.key]
+            return
-        keys.extend(self.falyx.exit_command.aliases)
+
-        if self.falyx.history_command:
+        leaf_tokens = list(route.leaf_argv)
-            keys.append(self.falyx.history_command.key)
+        if route.stub:
-            keys.extend(self.falyx.history_command.aliases)
+            leaf_tokens.append(route.stub)
-        if self.falyx.help_command:
+
-            keys.append(self.falyx.help_command.key)
+        try:
-            keys.extend(self.falyx.help_command.aliases)
+            suggestions = route.command.arg_parser.suggest_next(
-        for cmd in self.falyx.commands.values():
+                leaf_tokens,
-            keys.append(cmd.key)
+                route.cursor_at_end_of_token,
-            keys.extend(cmd.aliases)
+            )
-        for key in keys:
+        except Exception:
-            if key.upper().startswith(prefix):
+            return
-                yield Completion(key, start_position=-len(prefix))
+
+        yield from self._yield_lcp_completions(suggestions, route.stub)
+
+    def _suggest_namespace_entries(self, namespace: Falyx, prefix: str) -> list[str]:
+        """Return matching visible entry names for a namespace prefix.
+
+        This helper filters the current namespace's visible completion names so
+        only entries beginning with the provided prefix are returned. Case of the
+        returned value is adjusted to follow the case style of the typed prefix.
+
+        Args:
+            namespace (Falyx): Namespace whose entries should be searched for
+                completion candidates.
+            prefix (str): Current partially typed entry name.
+
+        Returns:
+            list[str]: Matching namespace entry keys and aliases.
+        """
+        results: list[str] = []
+        for name in namespace.completion_names:
+            if name.upper().startswith(prefix.upper()):
+                results.append(name.lower() if prefix.islower() else name)
+        return results
+
+    def _ensure_quote(self, text: str) -> str:
+        """Quote a completion candidate when it contains whitespace.
+
+        Args:
+            text (str): Raw completion candidate.
+
+        Returns:
+            str: Shell-safe candidate wrapped in double quotes when needed.
+        """
+        if " " in text or "\t" in text:
+            return f'"{text}"'
+        return text
+
+    def _yield_lcp_completions(self, suggestions, stub) -> Iterable[Completion]:
+        """Yield completions for the current stub using longest-common-prefix logic.
+
+        Behavior:
+        - If only one match → yield it fully.
+        - If multiple matches share a longer prefix → insert the prefix, but also
+            display all matches in the menu.
+        - If no shared prefix → list all matches individually.
+
+        Args:
+            suggestions (list[str]): The raw suggestions to consider.
+            stub (str): The currently typed prefix (used to offset insertion).
+
+        Yields:
+            Completion: Completion objects for the Prompt Toolkit menu.
+        """
+
+        if not suggestions:
+            return
+
+        matches = list(dict.fromkeys(s for s in suggestions if s.startswith(stub)))
+        if not matches:
+            return
+
+        lcp = os.path.commonprefix(matches)
+
+        if len(matches) == 1:
+            match = matches[0]
+            yield Completion(
+                self._ensure_quote(match),
+                start_position=-len(stub),
+                display=match,
+            )
+            return
+
+        if len(lcp) > len(stub) and not lcp.startswith("-"):
+            yield Completion(
+                self._ensure_quote(lcp),
+                start_position=-len(stub),
+                display=lcp,
+            )
+
+        for match in matches:
+            yield Completion(
+                self._ensure_quote(match),
+                start_position=-len(stub),
+                display=match,
+            )

falyx/completer_types.py

@@ -0,0 +1,87 @@
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
+"""Completion route models for routed Falyx autocompletion.
+
+This module defines `CompletionRoute`, a lightweight value object used by the
+Falyx completion system to describe the partially resolved state of interactive
+input during autocompletion.
+
+`CompletionRoute` sits at the boundary between namespace routing and
+command-local argument completion. It captures enough information for the
+completer to determine whether it should continue suggesting namespace entries
+or delegate to a resolved command's argument parser.
+
+Typical usage:
+    - A user types part of a namespace path or command key.
+    - Falyx resolves as much of that path as possible.
+    - The resulting `CompletionRoute` describes the active namespace, any
+      resolved leaf command, the remaining argv fragment, and the current
+      token stub under the cursor.
+    - `FalyxCompleter` uses this information to decide what completions to
+      surface next.
+
+This module is intentionally small and focused. It does not perform routing or
+completion itself; it only models the routed state needed by the completer.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from falyx.context import InvocationContext
+
+if TYPE_CHECKING:
+    from falyx.command import Command
+    from falyx.falyx import Falyx
+
+
+@dataclass(slots=True)
+class CompletionRoute:
+    """Represents a partially resolved route used during autocompletion.
+
+    A `CompletionRoute` describes the current routed state of user input while
+    Falyx is generating interactive completions. It distinguishes between two
+    broad states:
+
+    - namespace-routing state, where the user is still selecting a visible entry
+      within the current namespace
+    - leaf-command state, where a concrete command has been resolved and the
+      remaining input should be completed by that command's argument parser
+
+    Attributes:
+        namespace (Falyx): The active namespace in which completion is currently
+            taking place.
+        context (InvocationContext): Invocation-path context used to preserve the
+            routed command path and render context-aware help or usage text.
+        command (Command | None): The resolved leaf command, if routing has
+            already reached a concrete command. Remains `None` while the user is
+            still navigating namespaces.
+        leaf_argv (list[str]): Remaining command-local argv tokens that belong to
+            the resolved leaf command. These are typically passed to the
+            command's argument parser for completion.
+        stub (str): The current token fragment under the cursor. This is the
+            partial text that completion candidates should replace or extend.
+        cursor_at_end_of_token (bool): Whether the cursor is positioned at the
+            end of a completed token boundary, such as immediately after a
+            trailing space.
+        expecting_entry (bool): Whether completion should suggest namespace
+            entries rather than command-local arguments.
+        is_preview (bool): Whether the input is in preview mode, such as when
+            the user begins the invocation with `?`.
+
+    Notes:
+        - This model is completion-only and is intentionally separate from
+          full execution routing types such as `RouteResult`.
+        - `CompletionRoute` does not validate or parse command arguments; it
+          only records the routed state needed to decide what should complete
+          next.
+    """
+
+    namespace: Falyx
+    context: InvocationContext
+    command: Command | None = None
+    leaf_argv: list[str] = field(default_factory=list)
+    stub: str = ""
+    cursor_at_end_of_token: bool = False
+    expecting_entry: bool = False
+    is_preview: bool = False

falyx/config.py

@@ -1,6 +1,40 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""config.py
+"""Configuration loader and schema definitions for the Falyx CLI framework.
-Configuration loader for Falyx CLI commands."""
+
+This module supports config-driven initialization of CLI commands and submenus
+from YAML or TOML files. It enables declarative command definitions, auto-imports
+Python callables from dotted paths, and wraps them in `Action` or `Command` objects
+as needed.
+
+Features:
+- Parses Falyx command and submenu definitions from YAML or TOML.
+- Supports hooks, retry policies, confirm prompts, spinners, aliases, and tags.
+- Dynamically imports Python functions/classes from `action:` strings.
+- Wraps user callables into Falyx `Command` or `Action` instances.
+- Validates prompt and retry configuration using `pydantic` models.
+
+Main Components:
+- `FalyxConfig`: Pydantic model for top-level config structure.
+- `RawCommand`: Intermediate command definition model from raw config.
+- `Submenu`: Schema for nested CLI menus.
+- `loader(path)`: Loads and returns a fully constructed `Falyx` instance.
+
+Typical Config (YAML):
+```yaml
+title: My CLI
+commands:
+  - key: A
+    description: Say hello
+    action: my_package.tasks.hello
+    aliases: [hi]
+    tags: [example]
+```
+
+Example:
+    from falyx.config import loader
+    cli = loader("falyx.yaml")
+    cli.run()
+"""
 from __future__ import annotations
 
 import importlib
@@ -85,7 +119,7 @@ class RawCommand(BaseModel):
     spinner_message: str = "Processing..."
     spinner_type: str = "dots"
     spinner_style: str = OneColors.CYAN
-    spinner_kwargs: dict[str, Any] = Field(default_factory=dict)
+    spinner_speed: float = 1.0
 
     before_hooks: list[Callable] = Field(default_factory=list)
     success_hooks: list[Callable] = Field(default_factory=list)

falyx/console.py

@@ -1,5 +1,18 @@
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
+"""Global console instance for Falyx CLI applications."""
 from rich.console import Console
 
-from falyx.themes import get_nord_theme
+from falyx.themes import OneColors, get_nord_theme
 
 console = Console(color_system="truecolor", theme=get_nord_theme())
+error_console = Console(color_system="truecolor", theme=get_nord_theme(), stderr=True)
+
+
+def print_error(
+    message: str | Exception,
+    *,
+    hint: str | None = None,
+) -> None:
+    error_console.print(f"[{OneColors.DARK_RED}]error:[/] {message}")
+    if hint:
+        error_console.print(f"[{OneColors.LIGHT_YELLOW}]hint:[/] {hint}")

falyx/context.py

@@ -1,30 +1,38 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""
+"""Context models for Falyx execution and invocation state.
-Execution context management for Falyx CLI actions.
 
-This module defines `ExecutionContext` and `SharedContext`, which are responsible for
+This module defines the core context objects used throughout Falyx to track both
-capturing per-action and cross-action metadata during CLI workflow execution. These
+runtime execution metadata and routed invocation-path state.
-context objects provide structured introspection, result tracking, error recording,
-and time-based performance metrics.
 
-- `ExecutionContext`: Captures runtime information for a single action execution,
+It provides:
-  including arguments, results, exceptions, timing, and logging.
+    - `ExecutionContext` for per-action execution details such as arguments,
-- `SharedContext`: Maintains shared state and result propagation across
+      results, exceptions, timing, and summary logging.
-  `ChainedAction` or `ActionGroup` executions.
+    - `SharedContext` for transient shared state across grouped or chained
+      actions, including propagated results, indexed errors, and arbitrary
+      shared data.
+    - `InvocationContext` for capturing the current routed command path as an
+      immutable value object that supports both plain-text and Rich-markup
+      rendering.
 
-These contexts enable rich introspection, traceability, and workflow coordination,
+Together, these models support Falyx lifecycle hooks, execution tracing,
-supporting hook lifecycles, retries, and structured output generation.
+history/introspection, and context-aware help and usage rendering across CLI
+and menu modes.
 """
 from __future__ import annotations
 
 import time
 from datetime import datetime
+from traceback import format_exception
 from typing import Any
 
 from pydantic import BaseModel, ConfigDict, Field
 from rich.console import Console
+from rich.markup import escape
+from rich.style import Style
 
 from falyx.console import console
+from falyx.display_types import StyledSegment
+from falyx.mode import FalyxMode
 
 
 class ExecutionContext(BaseModel):
@@ -75,7 +83,8 @@ class ExecutionContext(BaseModel):
     kwargs: dict = Field(default_factory=dict)
     action: Any
     result: Any | None = None
-    exception: BaseException | None = None
+    traceback: str | None = None
+    _exception: BaseException | None = None
 
     start_time: float | None = None
     end_time: float | None = None
@@ -122,6 +131,16 @@ class ExecutionContext(BaseModel):
     def status(self) -> str:
         return "OK" if self.success else "ERROR"
 
+    @property
+    def exception(self) -> BaseException | None:
+        return self._exception
+
+    @exception.setter
+    def exception(self, exc: BaseException | None):
+        self._exception = exc
+        if exc is not None:
+            self.traceback = "".join(format_exception(exc)).strip()
+
     @property
     def signature(self) -> str:
         """
@@ -138,6 +157,7 @@ class ExecutionContext(BaseModel):
             "name": self.name,
             "result": self.result,
             "exception": repr(self.exception) if self.exception else None,
+            "traceback": self.traceback,
             "duration": self.duration,
             "extra": self.extra,
         }
@@ -209,9 +229,9 @@ class SharedContext(BaseModel):
         results (list[Any]): Captures results from each action, in order of execution.
         errors (list[tuple[int, BaseException]]): Indexed list of errors from failed actions.
         current_index (int): Index of the currently executing action (used in chains).
-        is_parallel (bool): Whether the context is used in parallel mode (ActionGroup).
+        is_concurrent (bool): Whether the context is used in concurrent mode (ActionGroup).
         shared_result (Any | None): Optional shared value available to all actions in
-                                    parallel mode.
+                                    concurrent mode.
         share (dict[str, Any]): Custom shared key-value store for user-defined
                                 communication
             between actions (e.g., flags, intermediate data, settings).
@@ -234,7 +254,7 @@ class SharedContext(BaseModel):
     results: list[Any] = Field(default_factory=list)
     errors: list[tuple[int, BaseException]] = Field(default_factory=list)
     current_index: int = -1
-    is_parallel: bool = False
+    is_concurrent: bool = False
     shared_result: Any | None = None
 
     share: dict[str, Any] = Field(default_factory=dict)
@@ -249,11 +269,11 @@ class SharedContext(BaseModel):
 
     def set_shared_result(self, result: Any) -> None:
         self.shared_result = result
-        if self.is_parallel:
+        if self.is_concurrent:
             self.results.append(result)
 
     def last_result(self) -> Any:
-        if self.is_parallel:
+        if self.is_concurrent:
             return self.shared_result
         return self.results[-1] if self.results else None
 
@@ -264,14 +284,155 @@ class SharedContext(BaseModel):
         self.share[key] = value
 
     def __str__(self) -> str:
-        parallel_label = "Parallel" if self.is_parallel else "Sequential"
+        concurrent_label = "Concurrent" if self.is_concurrent else "Sequential"
         return (
-            f"<{parallel_label}SharedContext '{self.name}' | "
+            f"<{concurrent_label}SharedContext '{self.name}' | "
             f"Results: {self.results} | "
             f"Errors: {self.errors}>"
         )
 
 
+class InvocationContext(BaseModel):
+    """Immutable invocation-path context for routed Falyx help and execution.
+
+    `InvocationContext` captures the current displayable command path as the router
+    descends through namespaces and commands. It stores both the raw typed path
+    (`typed_path`) and a styled segment representation (`segments`) so the same
+    context can be rendered as plain text or Rich markup.
+
+    This model is intended to be treated as an immutable value object. Methods such
+    as `with_path_segment()` and `without_last_path_segment()` return new context
+    instances rather than mutating the existing one.
+
+    Attributes:
+        program (str): Root program name used in CLI-mode help and usage output.
+        program_style (Style | str): Rich style applied to the program name when rendering
+            `markup_path`.
+        typed_path (list[str]): Raw invocation tokens collected during routing,
+            excluding the root program name.
+        segments (list[StyledSegment]): Styled path segments used to render the
+            invocation path with Rich markup.
+        mode (FalyxMode): Active Falyx mode for this invocation context. This is
+            used to determine whether the path should include the program name.
+        is_preview (bool): Whether the current invocation is a preview flow rather
+            than a normal execution flow.
+    """
+
+    program: str = ""
+    program_style: Style | str = ""
+    typed_path: list[str] = Field(default_factory=list)
+    segments: list[StyledSegment] = Field(default_factory=list)
+    mode: FalyxMode = FalyxMode.MENU
+    is_preview: bool = False
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    @property
+    def is_cli_mode(self) -> bool:
+        """Whether this context should render using CLI path semantics.
+
+        Returns:
+            bool: `True` when the invocation is not in menu mode, meaning rendered
+            paths should include the program name. `False` when in menu mode.
+        """
+        return self.mode != FalyxMode.MENU
+
+    def with_path_segment(
+        self,
+        token: str,
+        *,
+        style: Style | str | None = None,
+    ) -> InvocationContext:
+        """Return a new context with one additional path segment appended.
+
+        This method preserves the current context and creates a new
+        `InvocationContext` with the provided token added to both `typed_path` and
+        `segments`.
+
+        Args:
+            token (str): Raw path token to append, such as a namespace key,
+                command key, or alias.
+            style (str | None): Optional Rich style for the appended segment.
+
+        Returns:
+            InvocationContext: A new context containing the appended path segment.
+        """
+        return InvocationContext(
+            program=self.program,
+            program_style=self.program_style,
+            typed_path=[*self.typed_path, token],
+            segments=[*self.segments, StyledSegment(text=token, style=style)],
+            mode=self.mode,
+            is_preview=self.is_preview,
+        )
+
+    def without_last_path_segment(self) -> InvocationContext:
+        """Return a new context with the last path segment removed.
+
+        This method preserves the current context and creates a new
+        `InvocationContext` with the last token removed from both `typed_path` and
+        `segments`.
+
+        Returns:
+            InvocationContext: A new context with the last path segment removed, or the
+            current context if no path segments are present.
+        """
+        if not self.typed_path:
+            return self
+        return InvocationContext(
+            program=self.program,
+            program_style=self.program_style,
+            typed_path=self.typed_path[:-1],
+            segments=self.segments[:-1],
+            mode=self.mode,
+            is_preview=self.is_preview,
+        )
+
+    @property
+    def plain_path(self) -> str:
+        """Render the invocation path as plain text.
+
+        In CLI mode, the rendered path includes the root program name followed by
+        all collected path segments. In menu mode, only the collected path segments
+        are rendered.
+
+        Returns:
+            str: Plain-text invocation path suitable for logs, comparisons, or
+            non-styled help output.
+        """
+        parts = [seg.text for seg in self.segments]
+        if self.is_cli_mode:
+            return " ".join([self.program, *parts]).strip()
+        return " ".join(parts).strip()
+
+    @property
+    def markup_path(self) -> str:
+        """Render the invocation path as escaped Rich markup.
+
+        In CLI mode, the root program name is included and styled with
+        `program_style` when provided. Each path segment is escaped and styled
+        using its associated `StyledSegment.style` value when present.
+
+        Returns:
+            str: Rich-markup invocation path suitable for help and usage rendering.
+        """
+        parts: list[str] = []
+        if self.is_cli_mode and self.program:
+            if self.program_style:
+                parts.append(
+                    f"[{self.program_style}]{escape(self.program)}[/{self.program_style}]"
+                )
+            else:
+                parts.append(escape(self.program))
+
+        for seg in self.segments:
+            if seg.style:
+                parts.append(f"[{seg.style}]{escape(seg.text)}[/{seg.style}]")
+            else:
+                parts.append(escape(seg.text))
+        return " ".join(parts).strip()
+
+
 if __name__ == "__main__":
     import asyncio
 

falyx/debug.py

@@ -1,5 +1,17 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""debug.py"""
+"""Provides debug logging hooks for Falyx action execution.
+
+This module defines lifecycle hook functions (`log_before`, `log_success`, `log_after`, `log_error`)
+that can be registered with a `HookManager` to trace command execution.
+
+Logs include:
+- Action invocation with argument signature
+- Success result (with truncation for large outputs)
+- Errors with full exception info
+- Total runtime duration after execution
+
+Also exports `register_debug_hooks()` to register all log hooks in bulk.
+"""
 from falyx.context import ExecutionContext
 from falyx.hook_manager import HookManager, HookType
 from falyx.logger import logger

falyx/display_types.py

@@ -0,0 +1,33 @@
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
+"""Display types for Falyx.
+
+This module defines data models used for representing styled display elements in
+Falyx's CLI output, such as command paths, namespaces, and TLDR examples. These
+models are designed to be simple containers for the raw text and styling
+information needed to render consistent and visually appealing CLI interfaces using
+the Rich library.
+
+It provides:
+    - `StyledSegment` for representing a single styled token.
+"""
+from pydantic import BaseModel, ConfigDict
+from rich.style import Style
+
+
+class StyledSegment(BaseModel):
+    """Styled path segment used to build Rich styled markup.
+
+    `StyledSegment` represents a single token. It stores the raw display
+    text and an optional Rich style so text can be rendered either
+    as plain text or styled markup.
+
+    Attributes:
+        text (str): Display text for this path segment.
+        style (str | None): Optional Rich style applied when rendering this
+            segment in markup output.
+    """
+
+    text: str
+    style: Style | str | None = None
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)

falyx/exceptions.py

@@ -1,13 +1,45 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""exceptions.py"""
+"""Defines all custom exception classes used in the Falyx CLI framework.
+
+These exceptions provide structured error handling for common failure cases,
+including command conflicts, invalid actions or hooks, parser errors, and execution guards
+like circuit breakers or empty workflows.
+
+All exceptions inherit from `FalyxError`, the base exception for the framework.
+
+Exception Hierarchy:
+- FalyxError
+    ├── CommandAlreadyExistsError
+    ├── InvalidHookError
+    ├── InvalidActionError
+    ├── NotAFalyxError
+    ├── CircuitBreakerOpen
+    ├── EmptyChainError
+    ├── EmptyGroupError
+    ├── EmptyPoolError
+    ├── CommandArgumentError
+    └── EntryNotFoundError
+
+These are raised internally throughout the Falyx system to signal user-facing or
+developer-facing problems that should be caught and reported.
+"""
 
 
 class FalyxError(Exception):
-    """Custom exception for the Menu class."""
+    """Base exception class for all Falyx CLI framework errors."""
+
+    def __init__(
+        self,
+        message: str | None = None,
+        hint: str | None = None,
+    ):
+        if message:
+            super().__init__(message)
+        self.hint = hint
 
 
 class CommandAlreadyExistsError(FalyxError):
-    """Exception raised when an command with the same key already exists in the menu."""
+    """Exception raised when an command with the same key already exists in the Falyx instance."""
 
 
 class InvalidHookError(FalyxError):
@@ -19,7 +51,7 @@ class InvalidActionError(FalyxError):
 
 
 class NotAFalyxError(FalyxError):
-    """Exception raised when the provided submenu is not an instance of Menu."""
+    """Exception raised when the provided object is not an instance of a Falyx class."""
 
 
 class CircuitBreakerOpen(FalyxError):
@@ -31,12 +63,159 @@ class EmptyChainError(FalyxError):
 
 
 class EmptyGroupError(FalyxError):
-    """Exception raised when the chain is empty."""
+    """Exception raised when the group is empty."""
 
 
 class EmptyPoolError(FalyxError):
-    """Exception raised when the chain is empty."""
+    """Exception raised when the pool is empty."""
 
 
-class CommandArgumentError(FalyxError):
+class UsageError(FalyxError):
+    """Exception raised when there is an error in the command usage."""
+
+    def __init__(
+        self,
+        message: str | None = None,
+        hint: str | None = None,
+        show_short_usage: bool = True,
+    ):
+        super().__init__(message, hint)
+        self.show_short_usage = show_short_usage
+
+
+class FalyxOptionError(UsageError):
+    """Exception raised when there is an error in the Falyx option parser."""
+
+
+class CommandArgumentError(UsageError):
     """Exception raised when there is an error in the command argument parser."""
+
+
+class ArgumentGroupError(CommandArgumentError):
+    """Exception raised when there is an error in the argument group."""
+
+
+class ArgumentParsingError(CommandArgumentError):
+    """Exception raised when there is an error during argument parsing."""
+
+    def __init__(
+        self,
+        message: str | None = None,
+        hint: str | None = None,
+        show_short_usage: bool = True,
+        command_key: str | None = None,
+        dest: str | None = None,
+        token: str | None = None,
+    ):
+        self.command_key = command_key
+        self.dest = dest
+        self.token = token
+        super().__init__(message, hint, show_short_usage)
+
+
+class EntryNotFoundError(UsageError):
+    """Exception raised when a routing entry is not found."""
+
+    def __init__(
+        self,
+        unknown_name: str,
+        suggestions: list[str] | None = None,
+        message_context: str = "",
+        show_short_usage: bool = True,
+    ):
+        self.unknown_name = unknown_name
+        self.suggestions = suggestions
+        self.message_context = message_context
+        super().__init__(
+            self.build_message(),
+            self.build_hint(),
+            show_short_usage,
+        )
+
+    def build_message(self) -> str:
+        prefix = f"{self.message_context}: " if self.message_context else ""
+        return f"{prefix}unknown command or namespace '{self.unknown_name}'."
+
+    def build_hint(self) -> str | None:
+        if self.suggestions:
+            return f"did you mean: {', '.join(self.suggestions[:10])}?"
+        else:
+            return None
+
+
+class UnrecognizedOptionError(ArgumentParsingError):
+    def __init__(
+        self,
+        token: str,
+        remaining_flags: list[str] | None = None,
+        show_short_usage: bool = True,
+    ):
+        self.remaining_flags = remaining_flags
+        self.token = token
+        super().__init__(
+            self.build_message(),
+            self.build_hint(),
+            show_short_usage=show_short_usage,
+            token=token,
+        )
+
+    def build_message(self) -> str:
+        return f"unrecognized option '{self.token}'"
+
+    def build_hint(self) -> str:
+        if self.remaining_flags:
+            return f"did you mean one of: {', '.join(self.remaining_flags)}?"
+        return "use --help to see available options"
+
+
+class InvalidValueError(ArgumentParsingError):
+    def __init__(
+        self,
+        dest: str | None = None,
+        choices: list[str] | None = None,
+        expected: str | None = None,
+        error: Exception | str | None = None,
+        show_short_usage: bool = True,
+    ):
+        self.choices = choices
+        self.expected = expected
+        self.error = error
+        self.dest = dest
+        super().__init__(
+            self.build_message(),
+            self.build_hint(),
+            show_short_usage=show_short_usage,
+            dest=dest,
+        )
+
+    def build_message(self) -> str:
+        if self.dest and self.choices:
+            return f"invalid value for '{self.dest}'"
+        elif self.dest and self.error:
+            return f"invalid value for '{self.dest}': {self.error}"
+        elif self.dest and self.expected:
+            return f"invalid value for '{self.dest}': expected {self.expected}"
+        else:
+            return "invalid command argument value."
+
+    def build_hint(self) -> str | None:
+        if self.dest and self.choices:
+            return f"the value for '{self.dest}' must be one of {{{', '.join(self.choices)}}}."
+        else:
+            return None
+
+
+class MissingValueError(ArgumentParsingError):
+    def __init__(
+        self,
+        dest: str,
+        expected_count: int | None = None,
+        actual_count: int | None = None,
+    ):
+        self.expected_count = expected_count
+        self.actual_count = actual_count
+        self.dest = dest
+
+
+class TokenizationError(UsageError):
+    raw_input: str | None = None

falyx/execution_option.py

@@ -0,0 +1,61 @@
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
+"""Execution option enums for the Falyx command runtime.
+
+This module defines `ExecutionOption`, the enum used to represent optional
+execution-scoped behaviors that a command may choose to expose through its
+argument parser.
+
+Execution options are distinct from normal command inputs. They control runtime
+behavior around command execution rather than the business-logic arguments
+passed to the underlying action. Typical examples include summary output,
+retry configuration, and confirmation handling.
+
+`ExecutionOption` is used by Falyx components such as `Command` and
+`CommandArgumentParser` to declaratively enable execution-level flags and to
+normalize user- or config-provided option names into a validated enum value.
+
+The enum also implements custom missing-value handling so string inputs can be
+resolved case-insensitively with helpful error messages.
+"""
+from __future__ import annotations
+
+from enum import Enum
+
+
+class ExecutionOption(Enum):
+    """Enumerates optional execution-scoped behaviors supported by Falyx.
+
+    `ExecutionOption` identifies runtime features that can be enabled on a
+    command independently of its normal argument schema. When present, these
+    options typically cause `CommandArgumentParser` to expose additional flags
+    that affect how the command is executed rather than what the command does.
+
+    Supported options:
+        SUMMARY: Enable summary-related execution flags and reporting behavior.
+        RETRY: Enable retry-related execution flags such as retry count, delay,
+            and backoff.
+        CONFIRM: Enable confirmation-related execution flags such as forcing or
+            skipping confirmation prompts.
+
+    Notes:
+        - These values are intended for execution control, not domain-specific
+          command input.
+        - String values are normalized case-insensitively through `_missing_()`
+          so config and user input can be converted into enum members with
+          friendlier validation behavior.
+    """
+
+    SUMMARY = "summary"
+    RETRY = "retry"
+    CONFIRM = "confirm"
+
+    @classmethod
+    def _missing_(cls, value: object) -> ExecutionOption:
+        if not isinstance(value, str):
+            raise ValueError(f"Invalid {cls.__name__}: {value!r}")
+        normalized = value.strip().lower()
+        for member in cls:
+            if member.value == normalized:
+                return member
+        valid = ", ".join(member.value for member in cls)
+        raise ValueError(f"Invalid {cls.__name__}: '{value}'. Must be one of: {valid}")

falyx/execution_registry.py

@@ -1,29 +1,48 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""
+"""Provides the `ExecutionRegistry`, a centralized runtime store for capturing and
-execution_registry.py
+inspecting the execution history of Falyx actions.
 
-This module provides the `ExecutionRegistry`, a global class for tracking and
+The registry automatically records every `ExecutionContext` created during action
-introspecting the execution history of Falyx actions.
+execution—including context metadata, results, exceptions, duration, and tracebacks.
+It supports filtering, summarization, and visual inspection via a Rich-rendered table.
 
-The registry captures `ExecutionContext` instances from all executed actions, making it
+Designed for:
-easy to debug, audit, and visualize workflow behavior over time. It supports retrieval,
+- Workflow debugging and CLI diagnostics
-filtering, clearing, and formatted summary display.
+- Interactive history browsing or replaying previous runs
+- Providing user-visible `history` or `last-result` commands inside CLI apps
 
-Core Features:
+Key Features:
-- Stores all action execution contexts globally (with access by name).
+- Global, in-memory store of all `ExecutionContext` objects (by name, index, or full list)
-- Provides live execution summaries in a rich table format.
+- Thread-safe indexing and summary display
-- Enables creation of a built-in Falyx Action to print history on demand.
+- Traceback-aware result inspection and filtering by status (success/error)
-- Integrates with Falyx's introspectable and hook-driven execution model.
+- Used by built-in `History` command in Falyx CLI
-
-Intended for:
-- Debugging and diagnostics
-- Post-run inspection of CLI workflows
-- Interactive tools built with Falyx
 
 Example:
     from falyx.execution_registry import ExecutionRegistry as er
+
+    # Record a context
     er.record(context)
+
+    # Display a rich table summary
     er.summary()
+
+    # Print the last non-ignored result
+    er.summary(last_result=True)
+
+    # Clear execution history
+    er.summary(clear=True)
+
+Note:
+    The registry is volatile and cleared on each process restart or when `clear()` is called.
+    All data is retained in memory only.
+
+Public Interface:
+- record(context): Log an ExecutionContext and assign index.
+- get_all(): List all stored contexts.
+- get_by_name(name): Retrieve all contexts by action name.
+- get_latest(): Retrieve the most recent context.
+- clear(): Reset the registry.
+- summary(...): Rich console summary of stored execution results.
 """
 from __future__ import annotations
 
@@ -43,45 +62,46 @@ from falyx.themes import OneColors
 
 
 class ExecutionRegistry:
-    """
+    """Global registry for recording and inspecting Falyx action executions.
-    Global registry for recording and inspecting Falyx action executions.
 
-    This class captures every `ExecutionContext` generated by a Falyx `Action`,
+    This class captures every `ExecutionContext` created by Falyx Actions,
-    `ChainedAction`, or `ActionGroup`, maintaining both full history and
+    tracking metadata, results, exceptions, and performance metrics. It enables
-    name-indexed access for filtered analysis.
+    rich introspection, post-execution inspection, and formatted summaries
+    suitable for interactive and headless CLI use.
 
-    Methods:
+    Data is retained in memory until cleared or process exit.
-        - record(context): Stores an ExecutionContext, logging a summary line.
-        - get_all(): Returns the list of all recorded executions.
-        - get_by_name(name): Returns all executions with the given action name.
-        - get_latest(): Returns the most recent execution.
-        - clear(): Wipes the registry for a fresh run.
-        - summary(): Renders a formatted Rich table of all execution results.
 
     Use Cases:
-        - Debugging chained or factory-generated workflows
+        - Auditing chained or dynamic workflows
-        - Viewing results and exceptions from multiple runs
+        - Rendering execution history in a help/debug menu
-        - Embedding a diagnostic command into your CLI for user support
+        - Accessing previous results or errors for reuse
 
-    Note:
+    Attributes:
-        This registry is in-memory and not persistent. It's reset each time the process
+        _store_by_name (dict): Maps action name → list of ExecutionContext objects.
-        restarts or `clear()` is called.
+        _store_by_index (dict): Maps numeric index → ExecutionContext.
-
+        _store_all (list): Ordered list of all contexts.
-    Example:
+        _index (int): Global counter for assigning unique execution indices.
-        ExecutionRegistry.record(context)
+        _lock (Lock): Thread lock for atomic writes to the registry.
-        ExecutionRegistry.summary()
+        _console (Console): Rich console used for rendering summaries.
     """
 
     _store_by_name: dict[str, list[ExecutionContext]] = defaultdict(list)
     _store_by_index: dict[int, ExecutionContext] = {}
     _store_all: list[ExecutionContext] = []
-    _console = Console(color_system="truecolor")
+    _console: Console = console
     _index = 0
     _lock = Lock()
 
     @classmethod
     def record(cls, context: ExecutionContext):
-        """Record an execution context."""
+        """Record an execution context and assign a unique index.
+
+        This method logs the context, appends it to the registry,
+        and makes it available for future summary or filtering.
+
+        Args:
+            context (ExecutionContext): The context to be tracked.
+        """
         logger.debug(context.to_log_line())
         with cls._lock:
             context.index = cls._index
@@ -92,18 +112,40 @@ class ExecutionRegistry:
 
     @classmethod
     def get_all(cls) -> list[ExecutionContext]:
+        """Return all recorded execution contexts in order of execution.
+
+        Returns:
+            list[ExecutionContext]: All stored action contexts.
+        """
         return cls._store_all
 
     @classmethod
     def get_by_name(cls, name: str) -> list[ExecutionContext]:
+        """Return all executions recorded under a given action name.
+
+        Args:
+            name (str): The name of the action.
+
+        Returns:
+            list[ExecutionContext]: Matching contexts, or empty if none found.
+        """
         return cls._store_by_name.get(name, [])
 
     @classmethod
     def get_latest(cls) -> ExecutionContext:
+        """Return the most recent execution context.
+
+        Returns:
+            ExecutionContext: The last recorded context.
+        """
         return cls._store_all[-1]
 
     @classmethod
     def clear(cls):
+        """Clear all stored execution data and reset internal indices.
+
+        This operation is destructive and cannot be undone.
+        """
         cls._store_by_name.clear()
         cls._store_all.clear()
         cls._store_by_index.clear()
@@ -118,6 +160,20 @@ class ExecutionRegistry:
         last_result: bool = False,
         status: Literal["all", "success", "error"] = "all",
     ):
+        """Display a formatted Rich table of recorded executions.
+
+        Supports filtering by action name, index, or execution status.
+        Can optionally show only the last result or a specific indexed result.
+        Also supports clearing the registry interactively.
+
+        Args:
+            name (str): Filter by action name.
+            index (int | None): Filter by specific execution index.
+            result_index (int | None): Print result (or traceback) of a specific index.
+            clear (bool): If True, clears the registry and exits.
+            last_result (bool): If True, prints only the most recent result.
+            status (Literal): One of "all", "success", or "error" to filter displayed rows.
+        """
         if clear:
             cls.clear()
             cls._console.print(f"[{OneColors.GREEN}]✅ Execution history cleared.")
@@ -125,13 +181,11 @@ class ExecutionRegistry:
 
         if last_result:
             for ctx in reversed(cls._store_all):
-                if ctx.name.upper() not in [
+                if not ctx.action.ignore_in_history:
-                    "HISTORY",
+                    cls._console.print(f"{ctx.signature}:")
-                    "HELP",
+                    if ctx.traceback:
-                    "EXIT",
+                        cls._console.print(ctx.traceback)
-                    "VIEW EXECUTION HISTORY",
+                    else:
-                    "BACK",
-                ]:
                         cls._console.print(ctx.result)
                     return
             cls._console.print(
@@ -148,8 +202,8 @@ class ExecutionRegistry:
                 )
                 return
             cls._console.print(f"{result_context.signature}:")
-            if result_context.exception:
+            if result_context.traceback:
-                cls._console.print(result_context.exception)
+                cls._console.print(result_context.traceback)
             else:
                 cls._console.print(result_context.result)
             return
@@ -205,8 +259,8 @@ class ExecutionRegistry:
             elif status.lower() in ["all", "success"]:
                 final_status = f"[{OneColors.GREEN}]✅ Success"
                 final_result = repr(ctx.result)
-                if len(final_result) > 1000:
+                if len(final_result) > 50:
-                    final_result = f"{final_result[:1000]}..."
+                    final_result = f"{final_result[:50]}..."
             else:
                 continue
 

falyx/hook_manager.py

@@ -1,5 +1,20 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""hook_manager.py"""
+"""Defines the `HookManager` and `HookType` used in the Falyx CLI framework to manage
+execution lifecycle hooks around actions and commands.
+
+The hook system enables structured callbacks for important stages in a Falyx action's
+execution, such as before execution, after success, upon error, and teardown. These
+can be used for logging, side effects, diagnostics, metrics, and rollback logic.
+
+Key Components:
+- HookType: Enum categorizing supported hook lifecycle stages
+- HookManager: Core class for registering and invoking hooks during action execution
+- Hook: Union of sync and async callables accepting an `ExecutionContext`
+
+Usage:
+    hooks = HookManager()
+    hooks.register(HookType.BEFORE, log_before)
+"""
 from __future__ import annotations
 
 import inspect
@@ -15,7 +30,26 @@ Hook = Union[
 
 
 class HookType(Enum):
-    """Enum for hook types to categorize the hooks."""
+    """Enum for supported hook lifecycle phases in Falyx.
+
+    HookType is used to classify lifecycle events that can be intercepted
+    with user-defined callbacks.
+
+    Members:
+        BEFORE: Run before the action is invoked.
+        ON_SUCCESS: Run after successful completion.
+        ON_ERROR: Run when an exception occurs.
+        AFTER: Run after success or failure (always runs).
+        ON_TEARDOWN: Run at the very end, for resource cleanup.
+
+    Aliases:
+        "success" → "on_success"
+        "error" → "on_error"
+        "teardown" → "on_teardown"
+
+    Example:
+        HookType("error") → HookType.ON_ERROR
+    """
 
     BEFORE = "before"
     ON_SUCCESS = "on_success"
@@ -28,13 +62,48 @@ class HookType(Enum):
         """Return a list of all hook type choices."""
         return list(cls)
 
+    @classmethod
+    def _get_alias(cls, value: str) -> str:
+        aliases = {
+            "success": "on_success",
+            "error": "on_error",
+            "teardown": "on_teardown",
+        }
+        return aliases.get(value, value)
+
+    @classmethod
+    def _missing_(cls, value: object) -> HookType:
+        if not isinstance(value, str):
+            raise ValueError(f"Invalid {cls.__name__}: {value!r}")
+        normalized = value.strip().lower()
+        alias = cls._get_alias(normalized)
+        for member in cls:
+            if member.value == alias:
+                return member
+        valid = ", ".join(member.value for member in cls)
+        raise ValueError(f"Invalid {cls.__name__}: '{value}'. Must be one of: {valid}")
+
     def __str__(self) -> str:
         """Return the string representation of the hook type."""
         return self.value
 
 
 class HookManager:
-    """HookManager"""
+    """Manages lifecycle hooks for a command or action.
+
+    `HookManager` tracks user-defined callbacks to be run at key points in a command's
+    lifecycle: before execution, on success, on error, after completion, and during
+    teardown. Both sync and async hooks are supported.
+
+    Methods:
+        register(hook_type, hook): Register a callable for a given HookType.
+        clear(hook_type): Remove hooks for one or all lifecycle stages.
+        trigger(hook_type, context): Execute all hooks of a given type.
+
+    Example:
+        hooks = HookManager()
+        hooks.register(HookType.BEFORE, my_logger)
+    """
 
     def __init__(self) -> None:
         self._hooks: dict[HookType, list[Hook]] = {
@@ -42,12 +111,24 @@ class HookManager:
         }
 
     def register(self, hook_type: HookType | str, hook: Hook):
-        """Raises ValueError if the hook type is not supported."""
+        """Register a new hook for a given lifecycle phase.
-        if not isinstance(hook_type, HookType):
+
+        Args:
+            hook_type (HookType | str): The hook category (e.g. "before", "on_success").
+            hook (Callable): The hook function to register.
+
+        Raises:
+            ValueError: If the hook type is invalid.
+        """
         hook_type = HookType(hook_type)
         self._hooks[hook_type].append(hook)
 
     def clear(self, hook_type: HookType | None = None):
+        """Clear registered hooks for one or all hook types.
+
+        Args:
+            hook_type (HookType | None): If None, clears all hooks.
+        """
         if hook_type:
             self._hooks[hook_type] = []
         else:
@@ -55,6 +136,16 @@ class HookManager:
                 self._hooks[ht] = []
 
     async def trigger(self, hook_type: HookType, context: ExecutionContext):
+        """Invoke all hooks registered for a given lifecycle phase.
+
+        Args:
+            hook_type (HookType): The lifecycle phase to trigger.
+            context (ExecutionContext): The execution context passed to each hook.
+
+        Raises:
+            Exception: Re-raises the original context.exception if a hook fails during
+                       ON_ERROR. Other hook exceptions are logged and skipped.
+        """
         if hook_type not in self._hooks:
             raise ValueError(f"Unsupported hook type: {hook_type}")
         for hook in self._hooks[hook_type]:
@@ -71,7 +162,6 @@ class HookManager:
                     context.name,
                     hook_error,
                 )
-
                 if hook_type == HookType.ON_ERROR:
                     assert isinstance(
                         context.exception, Exception

falyx/hooks.py

@@ -1,5 +1,31 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""hooks.py"""
+"""Defines reusable lifecycle hooks for Falyx Actions and Commands.
+
+This module includes:
+- `spinner_before_hook`: Automatically starts a spinner before an action runs.
+- `spinner_teardown_hook`: Stops and clears the spinner after the action completes.
+- `ResultReporter`: A success hook that displays a formatted result with duration.
+- `CircuitBreaker`: A failure-aware hook manager that prevents repeated execution
+  after a configurable number of failures.
+
+These hooks can be registered on `HookManager` instances via lifecycle stages
+(`before`, `on_error`, `after`, etc.) to enhance resiliency and observability.
+
+Intended for use with:
+- Actions that require user feedback during long-running operations.
+- Retryable or unstable actions
+- Interactive CLI feedback
+- Safety checks prior to execution
+
+Example usage:
+    breaker = CircuitBreaker(max_failures=3)
+    hooks.register(HookType.BEFORE, breaker.before_hook)
+    hooks.register(HookType.ON_ERROR, breaker.error_hook)
+    hooks.register(HookType.AFTER, breaker.after_hook)
+
+    reporter = ResultReporter()
+    hooks.register(HookType.ON_SUCCESS, reporter.report)
+"""
 import time
 from typing import Any, Callable
 
@@ -9,6 +35,38 @@ from falyx.logger import logger
 from falyx.themes import OneColors
 
 
+async def spinner_before_hook(context: ExecutionContext):
+    """Adds a spinner before the action starts."""
+    command = context.action
+    if command.options_manager is None:
+        return
+    sm = context.action.options_manager.spinners
+    if hasattr(command, "name"):
+        command_name = command.name
+    else:
+        command_name = command.key
+    await sm.add(
+        command_name,
+        command.spinner_message,
+        command.spinner_type,
+        command.spinner_style,
+        command.spinner_speed,
+    )
+
+
+async def spinner_teardown_hook(context: ExecutionContext):
+    """Removes the spinner after the action finishes (success or failure)."""
+    command = context.action
+    if command.options_manager is None:
+        return
+    if hasattr(command, "name"):
+        command_name = command.name
+    else:
+        command_name = command.key
+    sm = context.action.options_manager.spinners
+    await sm.remove(command_name)
+
+
 class ResultReporter:
     """Reports the success of an action."""
 

falyx/init.py

@@ -1,5 +1,22 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""init.py"""
+"""Project and global initializer for Falyx CLI environments.
+
+This module defines functions to bootstrap a new Falyx-based CLI project or
+create a global user-level configuration in `~/.config/falyx`.
+
+Functions:
+- `init_project(name: str)`: Creates a new CLI project folder with `tasks.py`
+  and `falyx.yaml` using example actions and config structure.
+- `init_global()`: Creates a shared config in the user's home directory for
+  defining reusable or always-available CLI commands.
+
+Generated files include:
+- `tasks.py`: Python module with `Action`, `ChainedAction`, and async examples
+- `falyx.yaml`: YAML config with command definitions for CLI entry points
+
+Used by:
+- The `falyx init` and `falyx init --global` commands
+"""
 from pathlib import Path
 
 from falyx.console import console

falyx/logger.py

@@ -1,5 +1,5 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""logger.py"""
+"""Global logger instance for Falyx CLI applications."""
 import logging
 
 logger: logging.Logger = logging.getLogger("falyx")

falyx/menu.py

@@ -1,3 +1,19 @@
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
+"""Defines `MenuOption` and `MenuOptionMap`, core components used to construct
+interactive menus within Falyx Actions such as `MenuAction` and `PromptMenuAction`.
+
+Each `MenuOption` represents a single actionable choice with a description,
+styling, and a bound `BaseAction`. `MenuOptionMap` manages collections of these
+options, including support for reserved keys like `B` (Back) and `X` (Exit), which
+can trigger navigation signals when selected.
+
+These constructs enable declarative and reusable menu definitions in both code and config.
+
+Key Components:
+- MenuOption: A user-facing label and action binding
+- MenuOptionMap: A key-aware container for menu options, with reserved entry support
+"""
+
 from __future__ import annotations
 
 from dataclasses import dataclass
@@ -12,7 +28,25 @@ from falyx.utils import CaseInsensitiveDict
 
 @dataclass
 class MenuOption:
-    """Represents a single menu option with a description and an action to execute."""
+    """
+    Represents a single menu entry, including its label and associated action.
+
+    Used in conjunction with `MenuOptionMap` to define interactive command menus.
+    Each `MenuOption` contains a description (shown to the user), a `BaseAction`
+    to execute when selected, and an optional Rich-compatible style.
+
+    Attributes:
+        description (str): The label shown next to the menu key.
+        action (BaseAction): The action to invoke when selected.
+        style (str): A Rich-compatible color/style string for UI display.
+
+    Methods:
+        render(key): Returns a Rich-formatted string for menu display.
+        render_prompt(key): Returns a `FormattedText` object for use in prompt placeholders.
+
+    Raises:
+        TypeError: If `description` is not a string or `action` is not a `BaseAction`.
+    """
 
     description: str
     action: BaseAction
@@ -37,8 +71,27 @@ class MenuOption:
 
 class MenuOptionMap(CaseInsensitiveDict):
     """
-    Manages menu options including validation, reserved key protection,
+    A container for storing and managing `MenuOption` objects by key.
-    and special signal entries like Quit and Back.
+
+    `MenuOptionMap` is used to define the set of available choices in a
+    Falyx menu. Keys are case-insensitive and mapped to `MenuOption` instances.
+    The map supports special reserved keys—`B` for Back and `X` for Exit—unless
+    explicitly disabled via `allow_reserved=False`.
+
+    This class enforces strict typing of menu options and prevents accidental
+    overwrites of reserved keys.
+
+    Args:
+        options (dict[str, MenuOption] | None): Initial options to populate the menu.
+        allow_reserved (bool): If True, allows overriding reserved keys.
+
+    Methods:
+        items(include_reserved): Returns an iterable of menu options,
+                                 optionally filtering out reserved keys.
+
+    Raises:
+        TypeError: If non-`MenuOption` values are assigned.
+        ValueError: If attempting to use or delete a reserved key without permission.
     """
 
     RESERVED_KEYS = {"B", "X"}
@@ -47,12 +100,16 @@ class MenuOptionMap(CaseInsensitiveDict):
         self,
         options: dict[str, MenuOption] | None = None,
         allow_reserved: bool = False,
+        disable_reserved: bool = False,
     ):
         super().__init__()
         self.allow_reserved = allow_reserved
         if options:
             self.update(options)
+        if not disable_reserved:
             self._inject_reserved_defaults()
+        else:
+            self.allow_reserved = True
 
     def _inject_reserved_defaults(self):
         from falyx.action import SignalAction

falyx/mode.py

@@ -0,0 +1,42 @@
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
+"""Runtime mode definitions for the Falyx CLI framework.
+
+This module defines `FalyxMode`, the enum used to represent the high-level
+operating mode of a Falyx application during parsing, routing, rendering, and
+execution.
+
+These modes describe the current intent of the runtime rather than any
+particular command. They are used throughout Falyx to coordinate behavior such
+as whether the application should show an interactive menu, execute a routed
+command, render help output, preview a command, or surface an error state.
+
+`FalyxMode` is commonly stored in shared runtime state and passed through
+invocation and parsing layers so UI rendering and execution flow remain
+consistent across CLI and menu-driven entrypoints.
+"""
+from enum import Enum
+
+
+class FalyxMode(Enum):
+    """Enumerates the high-level runtime modes used by Falyx.
+
+    `FalyxMode` provides a small set of application-wide states that describe
+    how the current invocation should be handled.
+
+    Attributes:
+        MENU: Interactive menu mode using Prompt Toolkit input and menu
+            rendering.
+        COMMAND: Direct command-execution mode for routed CLI or programmatic
+            invocation.
+        PREVIEW: Non-executing preview mode used to inspect a command before it
+            runs.
+        HELP: Help-rendering mode for namespace, command, or TLDR output.
+        ERROR: Error state used when invocation handling should surface a
+            failure condition.
+    """
+
+    MENU = "menu"
+    COMMAND = "command"
+    PREVIEW = "preview"
+    HELP = "help"
+    ERROR = "error"

falyx/namespace.py

@@ -0,0 +1,68 @@
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
+"""Namespace entry model for nested Falyx applications.
+
+This module defines `FalyxNamespace`, the lightweight metadata container used to
+register one `Falyx` instance inside another as a routed namespace entry.
+
+A `FalyxNamespace` describes how a nested application should appear and behave
+from the perspective of its parent namespace. It stores the public-facing key,
+description, aliases, styling, and visibility flags used for routing,
+completion, help rendering, and menu display, while holding a reference to the
+child `Falyx` runtime that should take over once the namespace is entered.
+
+This model is intentionally small and declarative. It does not implement
+routing, rendering, or execution itself; those responsibilities remain with the
+parent and child `Falyx` instances.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from rich.style import StyleType
+
+from falyx.context import InvocationContext
+from falyx.themes import OneColors
+
+if TYPE_CHECKING:
+    from falyx.falyx import Falyx
+
+
+@dataclass
+class FalyxNamespace:
+    """Represents a nested `Falyx` application exposed as a namespace entry.
+
+    `FalyxNamespace` is used by a parent `Falyx` instance to register and
+    describe a child `Falyx` runtime as a routable namespace. It provides the
+    metadata needed to expose that child namespace consistently across command
+    resolution, completion, help output, and menu rendering.
+
+    Attributes:
+        key (str): Primary identifier used to enter the namespace.
+        description (str): User-facing namespace description.
+        namespace (Falyx): Nested `Falyx` instance activated when this namespace is
+            selected.
+        aliases (list[str]): Optional alternate names that may also resolve to the same
+            namespace.
+        help_text (str): Optional short help text used in listings or help output.
+        style (StyleType): Rich style used when rendering the namespace key or aliases.
+        hidden (bool): Whether the namespace should be omitted from visible menus and
+            help listings.
+    """
+
+    key: str
+    description: str
+    namespace: Falyx
+    aliases: list[str] = field(default_factory=list)
+    help_text: str = ""
+    style: StyleType = OneColors.CYAN
+    hidden: bool = False
+
+    def get_help_signature(
+        self, invocation_context: InvocationContext
+    ) -> tuple[str, str, str | None]:
+        """Returns the usage signature for this namespace, used in help rendering."""
+        usage = f"{self.key} {self.namespace._get_usage_fragment(invocation_context)}"
+        if self.aliases:
+            usage += f" (aliases: {', '.join(self.aliases)})"
+        return usage, self.description, self.help_text

falyx/options_manager.py

@@ -1,43 +1,173 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""options_manager.py"""
+"""Option state management for Falyx CLI runtimes.
 
-from argparse import Namespace
+This module defines `OptionsManager`, a small utility responsible for
+storing, retrieving, and temporarily overriding runtime option values across
+named namespaces.
+
+Falyx uses this manager to hold global session- and execution-scoped flags such
+as verbosity, prompt suppression, confirmation behavior, and other mutable
+runtime settings. Options are stored in isolated namespace dictionaries so
+different layers of the runtime can share one manager without clobbering each
+other's state.
+
+In addition to basic get/set operations, the manager provides helpers for:
+
+- toggling boolean flags
+- exposing option access as zero-argument callables for UI bindings
+- temporarily overriding a namespace within a context manager
+- holding a shared `SpinnerManager` for spinner lifecycle integration
+
+Typical usage:
+    ```
+    options = OptionsManager()
+    options.from_mapping({"verbose": True})
+    if options.get("verbose"):
+        ...
+
+    with options.override_namespace({"skip_confirm": True}, "execution"):
+        ...
+    ```
+
+Attributes:
+    options (defaultdict[str, dict[str, Any]]): Mapping of namespace names to
+        option dictionaries.
+    spinners (SpinnerManager): Shared spinner manager available to runtime
+        components that need coordinated spinner rendering.
+"""
 from collections import defaultdict
-from typing import Any, Callable
+from contextlib import contextmanager
+from typing import Any, Callable, Iterator, Mapping
 
 from falyx.logger import logger
+from falyx.spinner_manager import SpinnerManager
 
 
 class OptionsManager:
-    """OptionsManager"""
+    """Manage mutable option values across named runtime namespaces.
 
-    def __init__(self, namespaces: list[tuple[str, Namespace]] | None = None) -> None:
+    `OptionsManager` is the central store for Falyx runtime flags. Each option
-        self.options: defaultdict = defaultdict(Namespace)
+    is stored under a namespace name such as `"default"` or `"execution"`,
+    allowing global settings and temporary execution-scoped overrides to
+    coexist in one shared object.
+
+    The manager supports direct reads and writes, boolean toggling, namespace
+    snapshots, and temporary override contexts. It also exposes small callable
+    wrappers that are useful when integrating option reads or toggles into UI
+    components such as bottom-bar controls or key bindings.
+
+    Args:
+        namespaces (list[tuple[str, dict[str, Any]]] | None): Optional initial
+            namespace/value pairs to preload into the manager.
+
+    Attributes:
+        options (defaultdict[str, dict[str, Any]]): Internal namespace-to-option
+            mapping.
+        spinners (SpinnerManager): Shared spinner manager used by other Falyx
+            runtime components.
+    """
+
+    def __init__(
+        self,
+        namespaces: list[tuple[str, dict[str, Any]]] | None = None,
+    ) -> None:
+        """Initialize the option manager.
+
+        Args:
+            namespaces (list[tuple[str, dict[str, Any]]] | None): Optional list
+                of `(namespace_name, values)` pairs to load during
+                initialization.
+        """
+        self.options: defaultdict = defaultdict(dict)
+        self.spinners = SpinnerManager()
         if namespaces:
             for namespace_name, namespace in namespaces:
-                self.from_namespace(namespace, namespace_name)
+                self.from_mapping(namespace, namespace_name)
 
-    def from_namespace(
+    def from_mapping(
-        self, namespace: Namespace, namespace_name: str = "cli_args"
+        self,
+        values: Mapping[str, Any],
+        namespace_name: str = "default",
     ) -> None:
-        self.options[namespace_name] = namespace
+        """Merge option values into a namespace.
+
+        Existing keys in the target namespace are updated in place. Missing
+        namespaces are created automatically.
+
+        Args:
+            values (Mapping[str, Any]): Mapping of option names to values.
+            namespace_name (str): Target namespace to update. Defaults to
+                `"default"`.
+        """
+        self.options[namespace_name].update(dict(values))
 
     def get(
-        self, option_name: str, default: Any = None, namespace_name: str = "cli_args"
+        self,
+        option_name: str,
+        default: Any = None,
+        namespace_name: str = "default",
     ) -> Any:
-        """Get the value of an option."""
+        """Return an option value from a namespace.
-        return getattr(self.options[namespace_name], option_name, default)
 
-    def set(self, option_name: str, value: Any, namespace_name: str = "cli_args") -> None:
+        Args:
-        """Set the value of an option."""
+            option_name (str): Name of the option to retrieve.
-        setattr(self.options[namespace_name], option_name, value)
+            default (Any): Value to return when the option is not present.
+                Defaults to `None`.
+            namespace_name (str): Namespace to read from. Defaults to
+                `"default"`.
 
-    def has_option(self, option_name: str, namespace_name: str = "cli_args") -> bool:
+        Returns:
-        """Check if an option exists in the namespace."""
+            Any: The stored option value if present, otherwise `default`.
-        return hasattr(self.options[namespace_name], option_name)
+        """
+        return self.options[namespace_name].get(option_name, default)
 
-    def toggle(self, option_name: str, namespace_name: str = "cli_args") -> None:
+    def set(
-        """Toggle a boolean option."""
+        self,
+        option_name: str,
+        value: Any,
+        namespace_name: str = "default",
+    ) -> None:
+        """Store an option value in a namespace.
+
+        Args:
+            option_name (str): Name of the option to set.
+            value (Any): Value to store.
+            namespace_name (str): Namespace to update. Defaults to `"default"`.
+        """
+        self.options[namespace_name][option_name] = value
+
+    def has_option(
+        self,
+        option_name: str,
+        namespace_name: str = "default",
+    ) -> bool:
+        """Return whether an option exists in a namespace.
+
+        Args:
+            option_name (str): Name of the option to check.
+            namespace_name (str): Namespace to inspect. Defaults to `"default"`.
+
+        Returns:
+            bool: `True` if the option exists in the namespace, otherwise
+            `False`.
+        """
+        return option_name in self.options[namespace_name]
+
+    def toggle(
+        self,
+        option_name: str,
+        namespace_name: str = "default",
+    ) -> None:
+        """Invert a boolean option in place.
+
+        Args:
+            option_name (str): Name of the option to toggle.
+            namespace_name (str): Namespace containing the option. Defaults to
+                `"default"`.
+
+        Raises:
+            TypeError: If the target option is missing or is not a boolean.
+        """
         current = self.get(option_name, namespace_name=namespace_name)
         if not isinstance(current, bool):
             raise TypeError(
@@ -49,9 +179,24 @@ class OptionsManager:
         )
 
     def get_value_getter(
-        self, option_name: str, namespace_name: str = "cli_args"
+        self,
+        option_name: str,
+        namespace_name: str = "default",
     ) -> Callable[[], Any]:
-        """Get the value of an option as a getter function."""
+        """Return a zero-argument callable that reads an option value.
+
+        This is useful for UI integrations that expect a callback instead of an
+        eagerly evaluated value.
+
+        Args:
+            option_name (str): Name of the option to read.
+            namespace_name (str): Namespace to read from. Defaults to
+                `"default"`.
+
+        Returns:
+            Callable[[], Any]: Function that returns the current option value
+            when called.
+        """
 
         def _getter() -> Any:
             return self.get(option_name, namespace_name=namespace_name)
@@ -59,17 +204,72 @@ class OptionsManager:
         return _getter
 
     def get_toggle_function(
-        self, option_name: str, namespace_name: str = "cli_args"
+        self,
+        option_name: str,
+        namespace_name: str = "default",
     ) -> Callable[[], None]:
-        """Get the toggle function for a boolean option."""
+        """Return a zero-argument callable that toggles a boolean option.
+
+        This is useful for key bindings, bottom-bar toggles, or other UI hooks
+        that need a callable action.
+
+        Args:
+            option_name (str): Name of the boolean option to toggle.
+            namespace_name (str): Namespace containing the option. Defaults to
+                `"default"`.
+
+        Returns:
+            Callable[[], None]: Function that toggles the option when called.
+        """
 
         def _toggle() -> None:
             self.toggle(option_name, namespace_name=namespace_name)
 
         return _toggle
 
-    def get_namespace_dict(self, namespace_name: str) -> Namespace:
+    def get_namespace_dict(self, namespace_name: str) -> dict[str, Any]:
-        """Return all options in a namespace as a dictionary."""
+        """Return a shallow copy of one namespace's option dictionary.
+
+        Args:
+            namespace_name (str): Namespace to snapshot.
+
+        Returns:
+            dict[str, Any]: Copy of the namespace's stored options.
+
+        Raises:
+            ValueError: If the requested namespace does not exist.
+        """
         if namespace_name not in self.options:
             raise ValueError(f"Namespace '{namespace_name}' not found.")
-        return vars(self.options[namespace_name])
+        return dict(self.options[namespace_name])
+
+    @contextmanager
+    def override_namespace(
+        self,
+        overrides: Mapping[str, Any],
+        namespace_name: str = "execution",
+    ) -> Iterator[None]:
+        """Temporarily apply option overrides within a namespace.
+
+        The current namespace contents are copied before the overrides are
+        applied. When the context exits, the original namespace state is
+        restored, even if an exception is raised inside the context block.
+
+        Args:
+            overrides (Mapping[str, Any]): Temporary option values to merge into
+                the namespace.
+            namespace_name (str): Namespace to override. Defaults to
+                `"execution"`.
+
+        Yields:
+            None: Control is yielded to the wrapped context block.
+
+        Raises:
+            ValueError: If the namespace does not already exist.
+        """
+        original = self.get_namespace_dict(namespace_name)
+        try:
+            self.from_mapping(values=overrides, namespace_name=namespace_name)
+            yield
+        finally:
+            self.options[namespace_name] = original

falyx/parser/__init__.py

@@ -1,21 +1,19 @@
-"""
+"""Falyx CLI Framework
-Falyx CLI Framework
 
-Copyright (c) 2025 rtj.dev LLC.
+Copyright (c) 2026 rtj.dev LLC.
 Licensed under the MIT License. See LICENSE file for details.
 """
 
 from .argument import Argument
 from .argument_action import ArgumentAction
 from .command_argument_parser import CommandArgumentParser
-from .parsers import FalyxParsers, get_arg_parsers, get_root_parser, get_subparsers
+from .falyx_parser import FalyxParser
+from .parse_result import ParseResult
 
 __all__ = [
     "Argument",
     "ArgumentAction",
     "CommandArgumentParser",
-    "get_arg_parsers",
+    "FalyxParser",
-    "get_root_parser",
+    "ParseResult",
-    "get_subparsers",
-    "FalyxParsers",
 ]

falyx/parser/argument.py

@@ -1,5 +1,37 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""argument.py"""
+"""Defines the `Argument` dataclass used by `CommandArgumentParser` to represent
+individual command-line parameters in a structured, introspectable format.
+
+Each `Argument` instance describes one CLI input, including its flags, type,
+default behavior, action semantics, help text, and optional resolver integration
+for dynamic evaluation.
+
+Falyx uses this structure to support a declarative CLI design, providing flexible
+argument parsing with full support for positional and keyword arguments, coercion,
+completion, and help rendering.
+
+Arguments should be created using `CommandArgumentParser.add_argument()`
+or defined in YAML configurations, allowing for rich introspection and validation.
+
+Key Attributes:
+- `flags`: One or more short/long flags (e.g. `-v`, `--verbose`)
+- `dest`: Internal name used as the key in parsed results
+- `action`: `ArgumentAction` enum describing behavior (store, count, resolve, etc.)
+- `type`: Type coercion or callable converter
+- `default`: Optional fallback value
+- `choices`: Allowed values, if restricted
+- `nargs`: Number of expected values (`int`, `'?'`, `'*'`, `'+'`)
+- `positional`: Whether this argument is positional (no flag)
+- `resolver`: Optional `BaseAction` to resolve argument value dynamically
+- `lazy_resolver`: Whether to defer resolution until needed
+- `suggestions`: Optional completions for interactive shells
+
+Used By:
+- `CommandArgumentParser`
+- `Falyx` runtime parsing
+- Rich-based CLI help generation
+- Completion and preview suggestions
+"""
 from dataclasses import dataclass
 from typing import Any
 
@@ -9,8 +41,7 @@ from falyx.parser.argument_action import ArgumentAction
 
 @dataclass
 class Argument:
-    """
+    """Represents a command-line argument.
-    Represents a command-line argument.
 
     Attributes:
         flags (tuple[str, ...]): Short and long flags for the argument.
@@ -26,6 +57,9 @@ class Argument:
         resolver (BaseAction | None):
             An action object that resolves the argument, if applicable.
         lazy_resolver (bool): True if the resolver should be called lazily, False otherwise
+        suggestions (list[str] | None): Optional completions for interactive shells
+        group (str | None): Optional name of the argument group this belongs to.
+        mutex_group (str | None): Optional name of the mutually exclusive group this belongs to.
     """
 
     flags: tuple[str, ...]
@@ -40,6 +74,9 @@ class Argument:
     positional: bool = False
     resolver: BaseAction | None = None
     lazy_resolver: bool = False
+    suggestions: list[str] | None = None
+    group: str | None = None
+    mutex_group: str | None = None
 
     def get_positional_text(self) -> str:
         """Get the positional text for the argument."""
@@ -97,6 +134,8 @@ class Argument:
             and self.positional == other.positional
             and self.default == other.default
             and self.help == other.help
+            and self.group == other.group
+            and self.mutex_group == other.mutex_group
         )
 
     def __hash__(self) -> int:
@@ -112,5 +151,7 @@ class Argument:
                 self.positional,
                 self.default,
                 self.help,
+                self.group,
+                self.mutex_group,
             )
         )

falyx/parser/argument_action.py

@@ -1,12 +1,54 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""argument_action.py"""
+"""Defines `ArgumentAction`, an enum used to standardize the behavior of CLI arguments
+defined within Falyx command configurations.
+
+Each member of this enum maps to a valid `argparse` like actions or Falyx-specific
+behavior used during command argument parsing. This allows declarative configuration
+of argument behavior when building CLI commands via `CommandArgumentParser`.
+
+Supports alias coercion for shorthand or config-friendly values, and provides
+a consistent interface for downstream argument handling logic.
+
+Exports:
+    - ArgumentAction: Enum of allowed actions for command arguments.
+
+Example:
+    ArgumentAction("store_true") → ArgumentAction.STORE_TRUE
+    ArgumentAction("true")       → ArgumentAction.STORE_TRUE (via alias)
+    ArgumentAction("optional")   → ArgumentAction.STORE_BOOL_OPTIONAL
+"""
 from __future__ import annotations
 
 from enum import Enum
 
 
 class ArgumentAction(Enum):
-    """Defines the action to be taken when the argument is encountered."""
+    """Defines the action to be taken when the argument is encountered.
+
+    This enum mirrors the core behavior of Python's `argparse` actions, with a few
+    Falyx-specific extensions. It is used when defining command-line arguments for
+    `CommandArgumentParser` or YAML-based argument definitions.
+
+    Members:
+        ACTION: Invoke a callable as the argument handler (Falyx extension).
+        STORE: Store the provided value (default).
+        STORE_TRUE: Store `True` if the flag is present.
+        STORE_FALSE: Store `False` if the flag is present.
+        STORE_BOOL_OPTIONAL: Accept an optional bool (e.g., `--debug` or `--no-debug`).
+        APPEND: Append the value to a list.
+        EXTEND: Extend a list with multiple values.
+        COUNT: Count the number of occurrences.
+        HELP: Display help and exit.
+        TLDR: Display brief examples and exit.
+
+    Aliases:
+        - "true" → "store_true"
+        - "false" → "store_false"
+        - "optional" → "store_bool_optional"
+
+    Example:
+        ArgumentAction("true") → ArgumentAction.STORE_TRUE
+    """
 
     ACTION = "action"
     STORE = "store"
@@ -17,12 +59,34 @@ class ArgumentAction(Enum):
     EXTEND = "extend"
     COUNT = "count"
     HELP = "help"
+    TLDR = "tldr"
 
     @classmethod
     def choices(cls) -> list[ArgumentAction]:
         """Return a list of all argument actions."""
         return list(cls)
 
+    @classmethod
+    def _get_alias(cls, value: str) -> str:
+        aliases = {
+            "optional": "store_bool_optional",
+            "true": "store_true",
+            "false": "store_false",
+        }
+        return aliases.get(value, value)
+
+    @classmethod
+    def _missing_(cls, value: object) -> ArgumentAction:
+        if not isinstance(value, str):
+            raise ValueError(f"Invalid {cls.__name__}: {value!r}")
+        normalized = value.strip().lower()
+        alias = cls._get_alias(normalized)
+        for member in cls:
+            if member.value == alias:
+                return member
+        valid = ", ".join(member.value for member in cls)
+        raise ValueError(f"Invalid {cls.__name__}: '{value}'. Must be one of: {valid}")
+
     def __str__(self) -> str:
         """Return the string representation of the argument action."""
         return self.value

falyx/parser/falyx_parser.py

@@ -0,0 +1,650 @@
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING, Any
+
+from falyx.console import console
+from falyx.exceptions import EntryNotFoundError, FalyxOptionError
+from falyx.mode import FalyxMode
+from falyx.options_manager import OptionsManager
+from falyx.parser.parse_result import ParseResult
+from falyx.parser.parser_types import (
+    FalyxTLDRExample,
+    FalyxTLDRInput,
+    false_none,
+    true_none,
+)
+from falyx.parser.utils import coerce_value, get_type_name
+
+if TYPE_CHECKING:
+    from falyx.falyx import Falyx
+
+builtin_type = type
+
+
+class OptionAction(Enum):
+    STORE = "store"
+    STORE_TRUE = "store_true"
+    STORE_FALSE = "store_false"
+    STORE_BOOL_OPTIONAL = "store_bool_optional"
+    COUNT = "count"
+    HELP = "help"
+    TLDR = "tldr"
+
+    @classmethod
+    def choices(cls) -> list[OptionAction]:
+        """Return a list of all argument actions."""
+        return list(cls)
+
+    @classmethod
+    def _get_alias(cls, value: str) -> str:
+        aliases = {
+            "optional": "store_bool_optional",
+            "true": "store_true",
+            "false": "store_false",
+        }
+        return aliases.get(value, value)
+
+    @classmethod
+    def _missing_(cls, value: object) -> OptionAction:
+        if not isinstance(value, str):
+            raise ValueError(f"Invalid {cls.__name__}: {value!r}")
+        normalized = value.strip().lower()
+        alias = cls._get_alias(normalized)
+        for member in cls:
+            if member.value == alias:
+                return member
+        valid = ", ".join(member.value for member in cls)
+        raise ValueError(f"Invalid {cls.__name__}: '{value}'. Must be one of: {valid}")
+
+    def __str__(self) -> str:
+        """Return the string representation of the argument action."""
+        return self.value
+
+
+class OptionScope(Enum):
+    ROOT = "root"
+    NAMESPACE = "namespace"
+
+    @classmethod
+    def _missing_(cls, value: object) -> OptionScope:
+        if not isinstance(value, str):
+            raise ValueError(f"Invalid {cls.__name__}: {value!r}")
+        normalized = value.strip().lower()
+        for member in cls:
+            if member.value == normalized:
+                return member
+        valid = ", ".join(member.value for member in cls)
+        raise ValueError(f"Invalid {cls.__name__}: '{value}'. Must be one of: {valid}")
+
+
+@dataclass(slots=True)
+class Option:
+    flags: tuple[str, ...]
+    dest: str
+    action: OptionAction = OptionAction.STORE
+    type: Any = str
+    default: Any = None
+    choices: list[str] | None = None
+    help: str = ""
+    suggestions: list[str] | None = None
+    scope: OptionScope = OptionScope.NAMESPACE
+
+    def format_for_help(self) -> str:
+        """Return a formatted string of the option's flags for help output."""
+        return ", ".join(self.flags)
+
+
+class FalyxParser:
+    RESERVED_DESTS: set[str] = {"help", "tldr"}
+
+    def __init__(self, flx: Falyx) -> None:
+        self._flx = flx
+        self._options_by_dest: dict[str, Option] = {}
+        self._options: list[Option] = []
+        self._dest_set: set[str] = set()
+        self._tldr_examples: list[FalyxTLDRExample] = []
+        self._add_reserved_options()
+        self.help_option: Option | None = None
+        self.tldr_option: Option | None = None
+
+    def get_flags(self) -> list[str]:
+        """Return a list of the first flag for the registered options."""
+        return [option.flags[0] for option in self._options]
+
+    def get_options(self) -> list[Option]:
+        """Return a list of registered options."""
+        return self._options
+
+    def _add_tldr(self):
+        """Add TLDR argument to the parser."""
+        if "tldr" in self._dest_set:
+            return None
+        tldr = Option(
+            flags=("--tldr", "-T"),
+            action=OptionAction.TLDR,
+            help="Show quick usage examples.",
+            dest="tldr",
+            default=False,
+        )
+        self._register_option(tldr)
+        self.tldr_option = tldr
+
+    def add_tldr_example(
+        self,
+        *,
+        entry_key: str,
+        usage: str,
+        description: str,
+    ) -> None:
+        """Register a single namespace-level TLDR example.
+
+        The referenced entry must resolve to a known command or namespace in the
+        current `Falyx` instance. Unknown entries are reported to the console and
+        are not added.
+
+        Args:
+            entry_key (str): Command or namespace key the example is associated with.
+            usage (str): Example usage fragment shown after the resolved invocation path.
+            description (str): Short explanation displayed alongside the example.
+
+        Raises:
+            EntryNotFoundError: If `entry_key` cannot be resolved to a known command or
+                namespace in this `Falyx` instance.
+        """
+        entry, suggestions = self._flx.resolve_entry(entry_key)
+        if not entry:
+            raise EntryNotFoundError(
+                unknown_name=entry_key,
+                suggestions=suggestions,
+                message_context="TLDR example",
+            )
+        self._tldr_examples.append(
+            FalyxTLDRExample(entry_key=entry_key, usage=usage, description=description)
+        )
+        self._add_tldr()
+
+    def add_tldr_examples(self, examples: list[FalyxTLDRInput]) -> None:
+        """Register multiple namespace-level TLDR examples.
+
+        Supports either `FalyxTLDRExample` objects or shorthand tuples of
+        `(entry_key, usage, description)`.
+
+        Args:
+            examples (list[FalyxTLDRInput]): Example definitions to validate and append.
+
+        Raises:
+            FalyxError: If an example has an unsupported shape.
+            EntryNotFoundError: If `entry_key` cannot be resolved to a known command or
+                namespace in this `Falyx` instance.
+        """
+        for example in examples:
+            if isinstance(example, FalyxTLDRExample):
+                entry, suggestions = self._flx.resolve_entry(example.entry_key)
+                if not entry:
+                    raise EntryNotFoundError(
+                        unknown_name=example.entry_key,
+                        suggestions=suggestions,
+                        message_context="TLDR example",
+                    )
+                self._tldr_examples.append(example)
+                self._add_tldr()
+            elif len(example) == 3:
+                entry_key, usage, description = example
+                self.add_tldr_example(
+                    entry_key=entry_key,
+                    usage=usage,
+                    description=description,
+                )
+                self._add_tldr()
+            else:
+                raise FalyxOptionError(
+                    f"invalid TLDR example format: {example}.\n"
+                    "examples must be either FalyxTLDRExample instances "
+                    "or tuples of (entry_key, usage, description).",
+                )
+
+    def _add_reserved_options(self) -> None:
+        help = Option(
+            flags=("-h", "--help", "?"),
+            dest="help",
+            action=OptionAction.HELP,
+            help="Show root-level help output and exit.",
+            default=False,
+        )
+        self._register_option(help)
+        self.help_option = help
+
+        if not self._flx.disable_verbose_option:
+            verbose = Option(
+                flags=("-v", "--verbose"),
+                dest="verbose",
+                action=OptionAction.STORE_TRUE,
+                help="Enable verbose logging for the session.",
+                default=False,
+                scope=OptionScope.ROOT,
+            )
+            self._register_option(verbose)
+
+        if not self._flx.disable_debug_hooks_option:
+            debug_hooks = Option(
+                flags=("-d", "--debug-hooks"),
+                dest="debug_hooks",
+                action=OptionAction.STORE_TRUE,
+                help="Log hook execution in detail for the session.",
+                default=False,
+                scope=OptionScope.ROOT,
+            )
+            self._register_option(debug_hooks)
+
+        if not self._flx.disable_never_prompt_option:
+            never_prompt = Option(
+                flags=("-n", "--never-prompt"),
+                dest="never_prompt",
+                action=OptionAction.STORE_TRUE,
+                help="Suppress all prompts for the session.",
+                default=False,
+                scope=OptionScope.ROOT,
+            )
+            self._register_option(never_prompt)
+
+    def _register_store_bool_optional(
+        self,
+        flags: tuple[str, ...],
+        dest: str,
+        help: str,
+    ) -> None:
+        """Register a store_bool_optional action with the parser."""
+        if len(flags) != 1:
+            raise FalyxOptionError(
+                "store_bool_optional action can only have a single flag"
+            )
+        if not flags[0].startswith("--"):
+            raise FalyxOptionError(
+                "store_bool_optional action must use a long flag (e.g. --flag)"
+            )
+        base_flag = flags[0]
+        negated_flag = f"--no-{base_flag.lstrip('-')}"
+
+        argument = Option(
+            flags=flags,
+            dest=dest,
+            action=OptionAction.STORE_BOOL_OPTIONAL,
+            type=true_none,
+            default=None,
+            help=help,
+        )
+
+        negated_argument = Option(
+            flags=(negated_flag,),
+            dest=dest,
+            action=OptionAction.STORE_BOOL_OPTIONAL,
+            type=false_none,
+            default=None,
+            help=help,
+        )
+
+        self._register_option(argument)
+        self._register_option(negated_argument, bypass_validation=True)
+
+    def _register_option(self, option: Option, bypass_validation: bool = False) -> None:
+        self._dest_set.add(option.dest)
+        self._options.append(option)
+        for flag in option.flags:
+            if flag in self._options and not bypass_validation:
+                existing = self._options_by_dest[flag]
+                raise FalyxOptionError(
+                    f"flag '{flag}' is already used by argument '{existing.dest}'"
+                )
+            self._options_by_dest[flag] = option
+
+    def _validate_flags(self, flags: tuple[str, ...]) -> None:
+        if not flags:
+            raise FalyxOptionError("no flags provided for option")
+        for flag in flags:
+            if not isinstance(flag, str):
+                raise FalyxOptionError(f"invalid flag '{flag}': must be a string")
+            if not flag.startswith("-"):
+                raise FalyxOptionError(f"invalid flag '{flag}': must start with '-'")
+            if flag.startswith("--") and len(flag) < 3:
+                raise FalyxOptionError(
+                    f"invalid flag '{flag}': long flags must have at least one character after '--'"
+                )
+            if flag.startswith("-") and not flag.startswith("--") and len(flag) > 2:
+                raise FalyxOptionError(
+                    f"invalid flag '{flag}': short flags must be a single character"
+                )
+            if flag in self._options_by_dest:
+                existing = self._options_by_dest[flag]
+                raise FalyxOptionError(
+                    f"flag '{flag}' is already used by argument '{existing.dest}'"
+                )
+
+    def _get_dest_from_flags(self, flags: tuple[str, ...], dest: str | None) -> str:
+        if dest:
+            if not dest.replace("_", "").isalnum():
+                raise FalyxOptionError(
+                    f"invalid dest '{dest}': must be a valid identifier (letters, digits, and underscores only)"
+                )
+            if dest[0].isdigit():
+                raise FalyxOptionError(
+                    f"invalid dest '{dest}': cannot start with a digit"
+                )
+            return dest
+        dest = None
+        for flag in flags:
+            cleaned = flag.lstrip("-").replace("-", "_").lower()
+            dest = cleaned
+            if flag.startswith("--"):
+                break
+        assert dest is not None, "dest should not be None"
+        if not dest.replace("_", "").isalnum():
+            raise FalyxOptionError(
+                f"invalid dest '{dest}': must be a valid identifier (letters, digits, and underscores only)"
+            )
+        if dest[0].isdigit():
+            raise FalyxOptionError(f"invalid dest '{dest}': cannot start with a digit")
+        return dest
+
+    def _validate_action(self, action: str | OptionAction) -> OptionAction:
+        if isinstance(action, OptionAction):
+            return action
+        try:
+            return OptionAction(action)
+        except ValueError as error:
+            raise FalyxOptionError(
+                f"invalid option action '{action}' is not a valid OptionAction",
+                hint=f"valid actions are: {', '.join(a.value for a in OptionAction)}",
+            ) from error
+
+    def _resolve_default(
+        self,
+        default: Any,
+        action: OptionAction,
+    ) -> Any:
+        if default is None:
+            if action == OptionAction.STORE_TRUE:
+                return False
+            elif action == OptionAction.STORE_FALSE:
+                return True
+            elif action == OptionAction.STORE_BOOL_OPTIONAL:
+                return None
+            elif action == OptionAction.COUNT:
+                return 0
+        elif action is OptionAction.STORE_TRUE and default is not False:
+            raise FalyxOptionError(
+                f"default value for '{action}' action must be False or None, got {default!r}"
+            )
+        elif action is OptionAction.STORE_FALSE and default is not True:
+            raise FalyxOptionError(
+                f"default value for '{action}' action must be True or None, got {default!r}"
+            )
+        elif action is OptionAction.STORE_BOOL_OPTIONAL:
+            raise FalyxOptionError(
+                f"default value for '{action}' action must be None, got {default!r}"
+            )
+        elif action in (OptionAction.HELP, OptionAction.TLDR, OptionAction.COUNT):
+            raise FalyxOptionError(f"default value cannot be set for action '{action}'.")
+        return default
+
+    def _validate_default_type(
+        self,
+        default: Any,
+        expected_type: Any,
+        dest: str,
+    ) -> None:
+        if default is None:
+            return None
+        try:
+            coerce_value(default, expected_type)
+        except Exception as error:
+            type_name = get_type_name(expected_type)
+            raise FalyxOptionError(
+                f"invalid default value {default!r} for '{dest}' cannot be coerced to {type_name} error: {error}"
+            ) from error
+
+    def _normalize_choices(
+        self,
+        choices: list[str] | None,
+        expected_type: type,
+        action: OptionAction,
+    ) -> list[Any]:
+        if choices is None:
+            choices = []
+        else:
+            if action in (
+                OptionAction.STORE_TRUE,
+                OptionAction.STORE_FALSE,
+                OptionAction.STORE_BOOL_OPTIONAL,
+            ):
+                raise FalyxOptionError(
+                    f"choices cannot be specified for '{action}' actions"
+                )
+            if isinstance(choices, dict):
+                raise FalyxOptionError("choices cannot be a dict")
+            try:
+                choices = list(choices)
+            except TypeError as error:
+                raise FalyxOptionError(
+                    "choices must be iterable (like list, tuple, or set)"
+                ) from error
+        for choice in choices:
+            try:
+                coerce_value(choice, expected_type)
+            except Exception as error:
+                type_name = get_type_name(expected_type)
+                raise FalyxOptionError(
+                    f"invalid choice {choice!r} cannot be coerced to {type_name} error: {error}"
+                ) from error
+        return choices
+
+    def add_option(
+        self,
+        flags: tuple[str, ...],
+        dest: str,
+        action: str | OptionAction = "store",
+        type: type = str,
+        default: Any = None,
+        choices: list[str] | None = None,
+        help: str = "",
+        suggestions: list[str] | None = None,
+    ) -> None:
+        self._validate_flags(flags)
+        dest = self._get_dest_from_flags(flags, dest)
+        if dest in self.RESERVED_DESTS:
+            raise FalyxOptionError(
+                f"invalid dest '{dest}': '{dest}' is reserved and cannot be used as an option dest"
+            )
+        if dest in self._dest_set:
+            raise FalyxOptionError(f"duplicate option dest '{dest}'")
+        action = self._validate_action(action)
+        default = self._resolve_default(default, action)
+        self._validate_default_type(default, type, dest)
+        choices = self._normalize_choices(choices, type, action)
+        if default is not None and choices and default not in choices:
+            choices_str = ", ".join((str(choice) for choice in choices))
+            raise FalyxOptionError(
+                f"default value {default!r} is not in allowed choices: {choices_str}"
+            )
+        if suggestions is not None and not isinstance(suggestions, list):
+            type_name = get_type_name(suggestions)
+            raise FalyxOptionError(f"suggestions must be a list or None, got {type_name}")
+        if isinstance(suggestions, list) and not all(
+            isinstance(suggestion, str) for suggestion in suggestions
+        ):
+            raise FalyxOptionError("suggestions must be a list of strings")
+        if action is OptionAction.STORE_BOOL_OPTIONAL:
+            self._register_store_bool_optional(flags, dest, help)
+            return None
+        option = Option(
+            flags=flags,
+            dest=dest,
+            action=action,
+            type=type,
+            default=default,
+            choices=choices,
+            help=help,
+            suggestions=suggestions,
+        )
+        self._register_option(option)
+
+    def apply_to_options(
+        self,
+        parse_result: ParseResult,
+        options: OptionsManager,
+    ) -> None:
+        for dest, value in parse_result.options.items():
+            options.set(dest, value, namespace_name=self_flx.namespace_name)
+        for dest, value in parse_result.root_options.items():
+            options.set(dest, value, namespace_name="root")
+
+    def _can_bundle_option(self, option: Option) -> bool:
+        return option.action in {
+            OptionAction.STORE_TRUE,
+            OptionAction.STORE_FALSE,
+            OptionAction.COUNT,
+            OptionAction.HELP,
+            OptionAction.TLDR,
+        }
+
+    def _resolve_posix_bundling(self, tokens: list[str]) -> list[str]:
+        """Expand POSIX-style bundled arguments into separate arguments."""
+        expanded: list[str] = []
+        for token in tokens:
+            if not token.startswith("-") or token.startswith("--") or len(token) <= 2:
+                expanded.append(token)
+                continue
+
+            bundle = [f"-{char}" for char in token[1:]]
+
+            if (
+                all(
+                    flag in self._options_by_dest
+                    and self._can_bundle_option(self._options_by_dest[flag])
+                    for flag in bundle[:-1]
+                )
+                and bundle[-1] in self._options_by_dest
+            ):
+                expanded.extend(bundle)
+            else:
+                expanded.append(token)
+        return expanded
+
+    def _default_values(self) -> tuple[dict[str, Any], dict[str, Any]]:
+        values: dict[str, Any] = {}
+        root_values: dict[str, Any] = {}
+
+        for option in self._options:
+            if option.scope == OptionScope.ROOT:
+                root_values[option.dest] = option.default
+            elif option.scope == OptionScope.NAMESPACE:
+                values.setdefault(option.dest, option.default)
+            else:
+                assert False, f"unhandled option scope: {option.scope}"
+
+        return values, root_values
+
+    def _consume_option(
+        self,
+        option: Option,
+        argv: list[str],
+        index: int,
+        values: dict[str, Any],
+    ) -> int:
+        match option.action:
+            case OptionAction.STORE_TRUE:
+                values[option.dest] = True
+                return index + 1
+
+            case OptionAction.STORE_FALSE:
+                values[option.dest] = False
+                return index + 1
+
+            case OptionAction.STORE_BOOL_OPTIONAL:
+                values[option.dest] = option.type(None)
+                return index + 1
+
+            case OptionAction.COUNT:
+                values[option.dest] = int(values.get(option.dest) or 0) + 1
+                return index + 1
+
+            case OptionAction.HELP:
+                values[option.dest] = True
+                return index + 1
+
+            case OptionAction.TLDR:
+                values[option.dest] = True
+                return index + 1
+
+            case OptionAction.STORE:
+                value_index = index + 1
+                if value_index >= len(argv):
+                    raise FalyxOptionError(f"option '{argv[index]}' expected a value")
+
+                raw_value = argv[value_index]
+                try:
+                    value = coerce_value(raw_value, option.type)
+                except Exception as error:
+                    raise FalyxOptionError(
+                        f"invalid value for '{argv[index]}': {error}"
+                    ) from error
+
+                if option.choices and value not in option.choices:
+                    choices = ", ".join(str(choice) for choice in option.choices)
+                    raise FalyxOptionError(
+                        f"invalid value for '{argv[index]}': expected one of {{{choices}}}"
+                    )
+
+                values[option.dest] = value
+                return index + 2
+
+        raise FalyxOptionError(f"unsupported option action: {option.action}")
+
+    def parse_args(
+        self,
+        argv: list[str] | None = None,
+    ) -> ParseResult:
+        raw_argv = argv or []
+        arguments = self._resolve_posix_bundling(raw_argv)
+        values, root_values = self._default_values()
+
+        index = 0
+        while index < len(arguments):
+            token = arguments[index]
+
+            # Explicit option terminator. Everything after belongs to routing/command.
+            if token == "--":
+                index += 1
+                break
+
+            # First non-option is the route boundary.
+            if not token.startswith("-"):
+                break
+
+            # Unknown leading option is an error at this scope.
+            # This is what keeps root/namespace options honest.
+            option = self._options_by_dest.get(token)
+            if option is None:
+                raise FalyxOptionError(
+                    f"unknown option '{token}' for '{self._flx.program or self._flx.title}'"
+                )
+
+            target_values = root_values if option.scope == OptionScope.ROOT else values
+            index = self._consume_option(option, arguments, index, target_values)
+
+        remaining_argv = arguments[index:]
+
+        help_requested = values.get("help", False) or values.get("tldr", False)
+
+        return ParseResult(
+            mode=FalyxMode.HELP if help_requested else FalyxMode.COMMAND,
+            raw_argv=raw_argv,
+            options=values,
+            root_options=root_values,
+            remaining_argv=remaining_argv,
+            help=values.get("help", False),
+            tldr=values.get("tldr", False),
+            current_head=remaining_argv[0] if remaining_argv else "",
+        )

falyx/parser/group.py

@@ -0,0 +1,76 @@
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
+"""Argument grouping models for the Falyx command argument parser.
+
+This module defines lightweight dataclasses used by
+`CommandArgumentParser` to organize arguments into named help sections and
+mutually exclusive sets.
+
+It provides:
+
+- `ArgumentGroup`, which represents a logical collection of related argument
+  destinations for grouped help rendering.
+- `MutuallyExclusiveGroup`, which represents a set of argument destinations
+  where only one member may be selected, with optional group-level
+  requiredness.
+
+These models are metadata containers only. They do not perform parsing or
+validation themselves. Instead, they are populated and enforced by
+`CommandArgumentParser` during argument registration, parsing, and help
+generation.
+
+This module exists to keep argument-group state explicit, structured, and easy
+to introspect.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(slots=True)
+class ArgumentGroup:
+    """Represents a named group of related command argument destinations.
+
+    `ArgumentGroup` is used by `CommandArgumentParser` to collect arguments that
+    belong together conceptually so they can be rendered under a shared section
+    in help output and tracked as a unit in parser metadata.
+
+    This class stores only grouping metadata and does not implement any parsing
+    behavior on its own.
+
+    Attributes:
+        name: User-facing name of the argument group.
+        description: Optional descriptive text for the group, typically used in
+            help rendering.
+        dests: Destination names of arguments assigned to this group.
+    """
+
+    name: str
+    description: str = ""
+    dests: list[str] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class MutuallyExclusiveGroup:
+    """Represents a mutually exclusive set of argument destinations.
+
+    `MutuallyExclusiveGroup` is used by `CommandArgumentParser` to model groups
+    of arguments where only one member may be provided at a time. It can also
+    mark the group as required, meaning that exactly one of the grouped
+    arguments must be present.
+
+    This class stores group metadata only. Validation and enforcement are
+    performed by the parser.
+
+    Attributes:
+        name: User-facing name of the mutually exclusive group.
+        required: Whether at least one argument in the group must be supplied.
+        description: Optional descriptive text for the group, typically used in
+            help rendering.
+        dests: Destination names of arguments assigned to this mutually
+            exclusive group.
+    """
+
+    name: str
+    required: bool = False
+    description: str = ""
+    dests: list[str] = field(default_factory=list)

falyx/parser/parse_result.py

@@ -0,0 +1,64 @@
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
+"""Parse result model for the Falyx CLI runtime.
+
+This module defines `ParseResult`, the normalized output produced by the
+root-level Falyx parsing stage.
+
+`ParseResult` captures the session-scoped state derived from the initial
+CLI parse before namespace routing or command-local argument parsing begins. It
+records the selected top-level mode, the original argv, root option flags, and
+any remaining argv that should be forwarded into the routed execution layer.
+
+This model is typically produced by `FalyxParser.parse()` and then consumed by
+higher-level Falyx runtime entrypoints such as `Falyx.run()` to configure
+logging, prompt behavior, help rendering, and routed command dispatch.
+
+The dataclass is intentionally lightweight and focused on root parsing only. It
+does not perform parsing, validation, or execution itself.
+"""
+from dataclasses import dataclass, field
+from typing import Any
+
+from falyx.mode import FalyxMode
+
+
+@dataclass(slots=True)
+class ParseResult:
+    """Represents the normalized result of root-level Falyx argument parsing.
+
+    `ParseResult` stores the outcome of the initial CLI parse that occurs at
+    the application boundary. It separates session-level runtime settings from
+    the remaining argv that should continue into namespace routing and
+    command-local parsing.
+
+    This model is used to communicate root parsing decisions cleanly to the
+    rest of the Falyx runtime, including whether the application should enter
+    help mode or continue with normal command execution.
+
+    Attributes:
+        mode: Top-level runtime mode selected from the root parse.
+        raw_argv: Original argv passed into the root parser.
+        options: Dictionary of parsed root-level options and their values.
+        root_options: Dictionary of parsed root-level options that should be
+            applied at the root level for all namespaces.
+        remaining_argv: Unconsumed argv that should be forwarded to routed
+            command resolution.
+        current_head: The current head token being processed (for error reporting).
+        help: Whether help output was requested at the root level.
+        tldr: Whether TLDR output was requested at the root level.
+        verbose: Whether verbose logging should be enabled for the session.
+        debug_hooks: Whether hook execution should be logged in detail.
+        never_prompt: Whether prompts should be suppressed for the session.
+    """
+
+    mode: FalyxMode
+    raw_argv: list[str] = field(default_factory=list)
+    options: dict[str, Any] = field(default_factory=dict)
+    root_options: dict[str, Any] = field(default_factory=dict)
+    remaining_argv: list[str] = field(default_factory=list)
+    current_head: str = ""
+    help: bool = False
+    tldr: bool = False
+    verbose: bool = False
+    debug_hooks: bool = False
+    never_prompt: bool = False

falyx/parser/parser_types.py

@@ -1,15 +1,78 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""parser_types.py"""
+"""Type utilities and argument state models for Falyx's custom CLI argument parser.
-from typing import Any
+
+This module provides specialized helpers and data structures used by
+the `CommandArgumentParser` to handle non-standard parsing behavior.
+
+Contents:
+- `true_none` / `false_none`: Type coercion utilities that allow tri-state boolean
+  semantics (True, False, None). These are especially useful for supporting
+  `--flag` / `--no-flag` optional booleans in CLI arguments.
+- `ArgumentState`: Tracks whether an `Argument` has been consumed during parsing.
+- `TLDRExample`: A structured example for showing usage snippets and descriptions,
+   used in TLDR views.
+
+These tools support richer expressiveness and user-friendly ergonomics in
+Falyx's declarative command-line interfaces.
+"""
+from dataclasses import dataclass
+from typing import Any, TypeAlias
+
+from falyx.parser.argument import Argument
+
+
+@dataclass
+class ArgumentState:
+    """Tracks an argument and whether it has been consumed."""
+
+    arg: Argument
+    consumed: bool = False
+    consumed_position: int | None = None
+    has_invalid_choice: bool = False
+
+    def set_consumed(self, position: int | None = None) -> None:
+        """Mark this argument as consumed, optionally setting the position."""
+        self.consumed = True
+        self.consumed_position = position
+
+    def reset(self) -> None:
+        """Reset the consumed state."""
+        self.consumed = False
+        self.consumed_position = None
+
+
+@dataclass(frozen=True)
+class TLDRExample:
+    """Represents a usage example for TLDR output."""
+
+    usage: str
+    description: str
+
+
+TLDRInput: TypeAlias = TLDRExample | tuple[str, str]
+
+
+@dataclass(frozen=True)
+class FalyxTLDRExample:
+    """Represents a usage example for Falyx TLDR output, with optional metadata."""
+
+    entry_key: str
+    usage: str
+    description: str
+
+
+FalyxTLDRInput: TypeAlias = FalyxTLDRExample | tuple[str, str, str]
 
 
 def true_none(value: Any) -> bool | None:
+    """Return True if value is not None, else None."""
     if value is None:
         return None
     return True
 
 
 def false_none(value: Any) -> bool | None:
+    """Return False if value is not None, else None."""
     if value is None:
         return None
     return False

falyx/parser/parsers.py

@@ -1,383 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""parsers.py
-This module contains the argument parsers used for the Falyx CLI.
-"""
-from argparse import (
-    REMAINDER,
-    ArgumentParser,
-    Namespace,
-    RawDescriptionHelpFormatter,
-    _SubParsersAction,
-)
-from dataclasses import asdict, dataclass
-from typing import Any, Sequence
-
-from falyx.command import Command
-
-
-@dataclass
-class FalyxParsers:
-    """Defines the argument parsers for the Falyx CLI."""
-
-    root: ArgumentParser
-    subparsers: _SubParsersAction
-    run: ArgumentParser
-    run_all: ArgumentParser
-    preview: ArgumentParser
-    list: ArgumentParser
-    version: ArgumentParser
-
-    def parse_args(self, args: Sequence[str] | None = None) -> Namespace:
-        """Parse the command line arguments."""
-        return self.root.parse_args(args)
-
-    def as_dict(self) -> dict[str, ArgumentParser]:
-        """Convert the FalyxParsers instance to a dictionary."""
-        return asdict(self)
-
-    def get_parser(self, name: str) -> ArgumentParser | None:
-        """Get the parser by name."""
-        return self.as_dict().get(name)
-
-
-def get_root_parser(
-    prog: str | None = "falyx",
-    usage: str | None = None,
-    description: str | None = "Falyx CLI - Run structured async command workflows.",
-    epilog: (
-        str | None
-    ) = "Tip: Use 'falyx run ?[COMMAND]' to preview any command from the CLI.",
-    parents: Sequence[ArgumentParser] | None = None,
-    prefix_chars: str = "-",
-    fromfile_prefix_chars: str | None = None,
-    argument_default: Any = None,
-    conflict_handler: str = "error",
-    add_help: bool = True,
-    allow_abbrev: bool = True,
-    exit_on_error: bool = True,
-) -> ArgumentParser:
-    """
-    Construct the root-level ArgumentParser for the Falyx CLI.
-
-    This parser handles global arguments shared across subcommands and can serve
-    as the base parser for the Falyx CLI or standalone applications. It includes
-    options for verbosity, debug logging, and version output.
-
-    Args:
-        prog (str | None): Name of the program (e.g., 'falyx').
-        usage (str | None): Optional custom usage string.
-        description (str | None): Description shown in the CLI help.
-        epilog (str | None): Message displayed at the end of help output.
-        parents (Sequence[ArgumentParser] | None): Optional parent parsers.
-        prefix_chars (str): Characters to denote optional arguments (default: "-").
-        fromfile_prefix_chars (str | None): Prefix to indicate argument file input.
-        argument_default (Any): Global default value for arguments.
-        conflict_handler (str): Strategy to resolve conflicting argument names.
-        add_help (bool): Whether to include help (`-h/--help`) in this parser.
-        allow_abbrev (bool): Allow abbreviated long options.
-        exit_on_error (bool): Exit immediately on error or raise an exception.
-
-    Returns:
-        ArgumentParser: The root parser with global options attached.
-
-    Notes:
-        ```
-        Includes the following arguments:
-            --never-prompt       : Run in non-interactive mode.
-            -v / --verbose       : Enable debug logging.
-            --debug-hooks        : Enable hook lifecycle debug logs.
-            --version            : Print the Falyx version.
-        ```
-    """
-    parser = ArgumentParser(
-        prog=prog,
-        usage=usage,
-        description=description,
-        epilog=epilog,
-        parents=parents if parents else [],
-        prefix_chars=prefix_chars,
-        fromfile_prefix_chars=fromfile_prefix_chars,
-        argument_default=argument_default,
-        conflict_handler=conflict_handler,
-        add_help=add_help,
-        allow_abbrev=allow_abbrev,
-        exit_on_error=exit_on_error,
-    )
-    parser.add_argument(
-        "--never-prompt",
-        action="store_true",
-        help="Run in non-interactive mode with all prompts bypassed.",
-    )
-    parser.add_argument(
-        "-v", "--verbose", action="store_true", help=f"Enable debug logging for {prog}."
-    )
-    parser.add_argument(
-        "--debug-hooks",
-        action="store_true",
-        help="Enable default lifecycle debug logging",
-    )
-    parser.add_argument("--version", action="store_true", help=f"Show {prog} version")
-    return parser
-
-
-def get_subparsers(
-    parser: ArgumentParser,
-    title: str = "Falyx Commands",
-    description: str | None = "Available commands for the Falyx CLI.",
-) -> _SubParsersAction:
-    """
-    Create and return a subparsers object for registering Falyx CLI subcommands.
-
-    This function adds a `subparsers` block to the given root parser, enabling
-    structured subcommands such as `run`, `run-all`, `preview`, etc.
-
-    Args:
-        parser (ArgumentParser): The root parser to attach the subparsers to.
-        title (str): Title used in help output to group subcommands.
-        description (str | None): Optional text describing the group of subcommands.
-
-    Returns:
-        _SubParsersAction: The subparsers object that can be used to add new CLI subcommands.
-
-    Raises:
-        TypeError: If `parser` is not an instance of `ArgumentParser`.
-
-    Example:
-        ```python
-        >>> parser = get_root_parser()
-        >>> subparsers = get_subparsers(parser, title="Available Commands")
-        >>> subparsers.add_parser("run", help="Run a Falyx command")
-        ```
-    """
-    if not isinstance(parser, ArgumentParser):
-        raise TypeError("parser must be an instance of ArgumentParser")
-    subparsers = parser.add_subparsers(
-        title=title,
-        description=description,
-        dest="command",
-    )
-    return subparsers
-
-
-def get_arg_parsers(
-    prog: str | None = "falyx",
-    usage: str | None = None,
-    description: str | None = "Falyx CLI - Run structured async command workflows.",
-    epilog: (
-        str | None
-    ) = "Tip: Use 'falyx run ?[COMMAND]' to preview any command from the CLI.",
-    parents: Sequence[ArgumentParser] | None = None,
-    prefix_chars: str = "-",
-    fromfile_prefix_chars: str | None = None,
-    argument_default: Any = None,
-    conflict_handler: str = "error",
-    add_help: bool = True,
-    allow_abbrev: bool = True,
-    exit_on_error: bool = True,
-    commands: dict[str, Command] | None = None,
-    root_parser: ArgumentParser | None = None,
-    subparsers: _SubParsersAction | None = None,
-) -> FalyxParsers:
-    """
-    Create and return the full suite of argument parsers used by the Falyx CLI.
-
-    This function builds the root parser and all subcommand parsers used for structured
-    CLI workflows in Falyx. It supports standard subcommands including `run`, `run-all`,
-    `preview`, `list`, and `version`, and integrates with registered `Command` objects
-    to populate dynamic help and usage documentation.
-
-    Args:
-        prog (str | None): Program name to display in help and usage messages.
-        usage (str | None): Optional usage message to override the default.
-        description (str | None): Description for the CLI root parser.
-        epilog (str | None): Epilog message shown after the help text.
-        parents (Sequence[ArgumentParser] | None): Optional parent parsers.
-        prefix_chars (str): Characters that prefix optional arguments.
-        fromfile_prefix_chars (str | None): Prefix character for reading args from file.
-        argument_default (Any): Default value for arguments if not specified.
-        conflict_handler (str): Strategy for resolving conflicting arguments.
-        add_help (bool): Whether to add the `-h/--help` option to the root parser.
-        allow_abbrev (bool): Whether to allow abbreviated long options.
-        exit_on_error (bool): Whether the parser exits on error or raises.
-        commands (dict[str, Command] | None): Optional dictionary of registered commands
-            to populate help and subcommand descriptions dynamically.
-        root_parser (ArgumentParser | None): Custom root parser to use instead of building one.
-        subparsers (_SubParsersAction | None): Optional existing subparser object to extend.
-
-    Returns:
-        FalyxParsers: A structured container of all parsers, including `run`, `run-all`,
-                      `preview`, `list`, `version`, and the root parser.
-
-    Raises:
-        TypeError: If `root_parser` is not an instance of ArgumentParser or
-                   `subparsers` is not an instance of _SubParsersAction.
-
-    Example:
-        ```python
-        >>> parsers = get_arg_parsers(commands=my_command_dict)
-        >>> args = parsers.root.parse_args()
-        ```
-
-    Notes:
-        - This function integrates dynamic command usage and descriptions if the
-          `commands` argument is provided.
-        - The `run` parser supports additional options for retry logic and confirmation
-          prompts.
-        - The `run-all` parser executes all commands matching a tag.
-        - Use `falyx run ?[COMMAND]` from the CLI to preview a command.
-    """
-    if epilog is None:
-        epilog = f"Tip: Use '{prog} run ?[COMMAND]' to preview any command from the CLI."
-    if root_parser is None:
-        parser = get_root_parser(
-            prog=prog,
-            usage=usage,
-            description=description,
-            epilog=epilog,
-            parents=parents,
-            prefix_chars=prefix_chars,
-            fromfile_prefix_chars=fromfile_prefix_chars,
-            argument_default=argument_default,
-            conflict_handler=conflict_handler,
-            add_help=add_help,
-            allow_abbrev=allow_abbrev,
-            exit_on_error=exit_on_error,
-        )
-    else:
-        if not isinstance(root_parser, ArgumentParser):
-            raise TypeError("root_parser must be an instance of ArgumentParser")
-        parser = root_parser
-
-    if subparsers is None:
-        if prog == "falyx":
-            subparsers = get_subparsers(
-                parser,
-                title="Falyx Commands",
-                description="Available commands for the Falyx CLI.",
-            )
-        else:
-            subparsers = get_subparsers(parser, title="subcommands", description=None)
-    if not isinstance(subparsers, _SubParsersAction):
-        raise TypeError("subparsers must be an instance of _SubParsersAction")
-
-    run_description = ["Run a command by its key or alias.\n"]
-    run_description.append("commands:")
-    if isinstance(commands, dict):
-        for command in commands.values():
-            run_description.append(command.usage)
-            command_description = command.help_text or command.description
-            run_description.append(f"{' '*24}{command_description}")
-    run_epilog = (
-        f"Tip: Use '{prog} run ?[COMMAND]' to preview commands by their key or alias."
-    )
-    run_parser = subparsers.add_parser(
-        "run",
-        help="Run a specific command",
-        description="\n".join(run_description),
-        epilog=run_epilog,
-        formatter_class=RawDescriptionHelpFormatter,
-    )
-    run_parser.add_argument(
-        "name", help="Run a command by its key or alias", metavar="COMMAND"
-    )
-    run_parser.add_argument(
-        "--summary",
-        action="store_true",
-        help="Print an execution summary after command completes",
-    )
-    run_parser.add_argument(
-        "--retries", type=int, help="Number of retries on failure", default=0
-    )
-    run_parser.add_argument(
-        "--retry-delay",
-        type=float,
-        help="Initial delay between retries in (seconds)",
-        default=0,
-    )
-    run_parser.add_argument(
-        "--retry-backoff", type=float, help="Backoff factor for retries", default=0
-    )
-    run_group = run_parser.add_mutually_exclusive_group(required=False)
-    run_group.add_argument(
-        "-c",
-        "--confirm",
-        dest="force_confirm",
-        action="store_true",
-        help="Force confirmation prompts",
-    )
-    run_group.add_argument(
-        "-s",
-        "--skip-confirm",
-        dest="skip_confirm",
-        action="store_true",
-        help="Skip confirmation prompts",
-    )
-
-    run_parser.add_argument(
-        "command_args",
-        nargs=REMAINDER,
-        help="Arguments to pass to the command (if applicable)",
-        metavar="ARGS",
-    )
-
-    run_all_parser = subparsers.add_parser(
-        "run-all", help="Run all commands with a given tag"
-    )
-    run_all_parser.add_argument("-t", "--tag", required=True, help="Tag to match")
-    run_all_parser.add_argument(
-        "--summary",
-        action="store_true",
-        help="Print a summary after all tagged commands run",
-    )
-    run_all_parser.add_argument(
-        "--retries", type=int, help="Number of retries on failure", default=0
-    )
-    run_all_parser.add_argument(
-        "--retry-delay",
-        type=float,
-        help="Initial delay between retries in (seconds)",
-        default=0,
-    )
-    run_all_parser.add_argument(
-        "--retry-backoff", type=float, help="Backoff factor for retries", default=0
-    )
-    run_all_group = run_all_parser.add_mutually_exclusive_group(required=False)
-    run_all_group.add_argument(
-        "-c",
-        "--confirm",
-        dest="force_confirm",
-        action="store_true",
-        help="Force confirmation prompts",
-    )
-    run_all_group.add_argument(
-        "-s",
-        "--skip-confirm",
-        dest="skip_confirm",
-        action="store_true",
-        help="Skip confirmation prompts",
-    )
-
-    preview_parser = subparsers.add_parser(
-        "preview", help="Preview a command without running it"
-    )
-    preview_parser.add_argument("name", help="Key, alias, or description of the command")
-
-    list_parser = subparsers.add_parser(
-        "list", help="List all available commands with tags"
-    )
-
-    list_parser.add_argument(
-        "-t", "--tag", help="Filter commands by tag (case-insensitive)", default=None
-    )
-
-    version_parser = subparsers.add_parser("version", help=f"Show {prog} version")
-
-    return FalyxParsers(
-        root=parser,
-        subparsers=subparsers,
-        run=run_parser,
-        run_all=run_all_parser,
-        preview=preview_parser,
-        list=list_parser,
-        version=version_parser,
-    )

falyx/parser/signature.py

@@ -1,4 +1,14 @@
 # Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""Provides utilities for introspecting Python callables and extracting argument
+metadata compatible with Falyx's `CommandArgumentParser`.
+
+This module is primarily used to auto-generate command argument definitions from
+function signatures, enabling seamless integration of plain functions into the
+Falyx CLI with minimal boilerplate.
+
+Functions:
+- infer_args_from_func: Generate a list of argument definitions based on a function's signature.
+"""
 import inspect
 from typing import Any, Callable
 
@@ -9,9 +19,30 @@ def infer_args_from_func(
     func: Callable[[Any], Any] | None,
     arg_metadata: dict[str, str | dict[str, Any]] | None = None,
 ) -> list[dict[str, Any]]:
-    """
+    """Infer CLI-style argument definitions from a function signature.
-    Infer argument definitions from a callable's signature.
+
-    Returns a list of kwargs suitable for CommandArgumentParser.add_argument.
+    This utility inspects the parameters of a function and returns a list of dictionaries,
+    each of which can be passed to `CommandArgumentParser.add_argument()`.
+
+    It supports:
+    - Positional and keyword arguments
+    - Type hints for argument types
+    - Default values
+    - Required vs optional arguments
+    - Custom help text, choices, and suggestions via metadata
+
+    Note:
+        - Only parameters with kind `POSITIONAL_ONLY`, `POSITIONAL_OR_KEYWORD`, or
+          `KEYWORD_ONLY` are considered.
+        - Parameters with kind `VAR_POSITIONAL` or `VAR_KEYWORD` are ignored.
+
+    Args:
+        func (Callable | None): The function to inspect.
+        arg_metadata (dict | None): Optional metadata overrides for help text, type hints,
+                                    choices, and suggestions for each parameter.
+
+    Returns:
+        list[dict[str, Any]]: A list of argument definitions inferred from the function.
     """
     if not callable(func):
         logger.debug("Provided argument is not callable: %s", func)
@@ -54,8 +85,10 @@ def infer_args_from_func(
         if arg_type is bool:
             if param.default is False:
                 action = "store_true"
-            else:
+                default = None
+            elif param.default is True:
                 action = "store_false"
+                default = None
 
         if arg_type is list:
             action = "append"
@@ -75,6 +108,7 @@ def infer_args_from_func(
                 "action": action,
                 "help": metadata.get("help", ""),
                 "choices": metadata.get("choices"),
+                "suggestions": metadata.get("suggestions"),
             }
         )
 

falyx/parser/utils.py

@@ -1,4 +1,16 @@
 # Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""Contains value coercion and signature comparison utilities for Falyx argument parsing.
+
+This module provides type coercion functions for converting string input into expected
+Python types, including `Enum`, `bool`, `datetime`, and `Literal`. It also supports
+checking whether multiple actions share identical inferred argument definitions.
+
+Functions:
+- coerce_bool: Convert a string to a boolean.
+- coerce_enum: Convert a string or raw value to an Enum instance.
+- coerce_value: General-purpose coercion to a target type (including nested unions, enums, etc.).
+- same_argument_definitions: Check if multiple callables share the same argument structure.
+"""
 import types
 from datetime import datetime
 from enum import EnumMeta
@@ -11,7 +23,27 @@ from falyx.logger import logger
 from falyx.parser.signature import infer_args_from_func
 
 
+def get_type_name(type_: Any) -> str:
+    if hasattr(type_, "__name__"):
+        return type_.__name__
+    elif not isinstance(type_, type):
+        parent_type = type(type_)
+        if hasattr(parent_type, "__name__"):
+            return parent_type.__name__
+    return str(type_)
+
+
 def coerce_bool(value: str) -> bool:
+    """Convert a string to a boolean.
+
+    Accepts various truthy and falsy representations such as 'true', 'yes', '0', 'off', etc.
+
+    Args:
+        value (str): The input string or boolean.
+
+    Returns:
+        bool: Parsed boolean result.
+    """
     if isinstance(value, bool):
         return value
     value = value.strip().lower()
@@ -23,6 +55,20 @@ def coerce_bool(value: str) -> bool:
 
 
 def coerce_enum(value: Any, enum_type: EnumMeta) -> Any:
+    """Convert a raw value or string to an Enum instance.
+
+    Tries to resolve by name, value, or coerced base type.
+
+    Args:
+        value (Any): The input value to convert.
+        enum_type (EnumMeta): The target Enum class.
+
+    Returns:
+        Enum: The corresponding Enum instance.
+
+    Raises:
+        ValueError: If the value cannot be resolved to a valid Enum member.
+    """
     if isinstance(value, enum_type):
         return value
 
@@ -42,6 +88,20 @@ def coerce_enum(value: Any, enum_type: EnumMeta) -> Any:
 
 
 def coerce_value(value: str, target_type: type) -> Any:
+    """Attempt to convert a string to the given target type.
+
+    Handles complex typing constructs such as Union, Literal, Enum, and datetime.
+
+    Args:
+        value (str): The input string to convert.
+        target_type (type): The desired type.
+
+    Returns:
+        Any: The coerced value.
+
+    Raises:
+        ValueError: If conversion fails or the value is invalid.
+    """
     origin = get_origin(target_type)
     args = get_args(target_type)
 
@@ -79,7 +139,18 @@ def same_argument_definitions(
     actions: list[Any],
     arg_metadata: dict[str, str | dict[str, Any]] | None = None,
 ) -> list[dict[str, Any]] | None:
+    """Determine if multiple callables resolve to the same argument definitions.
 
+    This is used to infer whether actions in an ActionGroup or ProcessPool can share
+    a unified argument parser.
+
+    Args:
+        actions (list[Any]): A list of BaseAction instances or callables.
+        arg_metadata (dict | None): Optional overrides for argument help or type info.
+
+    Returns:
+        list[dict[str, Any]] | None: The shared argument definitions if consistent, else None.
+    """
     arg_sets = []
     for action in actions:
         if isinstance(action, BaseAction):

falyx/prompt_utils.py

@@ -1,29 +1,78 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""prompt_utils.py"""
+"""Utilities for user interaction prompts in the Falyx CLI framework.
+
+Provides asynchronous confirmation dialogs and helper logic to determine
+whether a user should be prompted based on command-line options.
+
+Includes:
+- `should_prompt_user()` for conditional prompt logic.
+- `confirm_async()` for interactive yes/no confirmation.
+"""
+from contextlib import contextmanager
+from typing import Iterator
+
 from prompt_toolkit import PromptSession
 from prompt_toolkit.formatted_text import (
     AnyFormattedText,
     FormattedText,
+    StyleAndTextTuples,
     merge_formatted_text,
 )
+from rich.console import Console
+from rich.text import Text
 
 from falyx.options_manager import OptionsManager
 from falyx.themes import OneColors
 from falyx.validators import yes_no_validator
 
 
+@contextmanager
+def prompt_session_context(session: PromptSession) -> Iterator[PromptSession]:
+    """Temporary override for prompt session management"""
+    message = session.message
+    validator = session.validator
+    placeholder = session.placeholder
+    try:
+        yield session
+    finally:
+        session.message = message
+        session.validator = validator
+        session.placeholder = placeholder
+
+
 def should_prompt_user(
     *,
     confirm: bool,
     options: OptionsManager,
-    namespace: str = "cli_args",
+    namespace: str = "root",
-):
+    override_namespace: str = "execution",
-    """
+) -> bool:
-    Determine whether to prompt the user for confirmation based on command
+    """Determine whether to prompt the user for confirmation.
-    and global options.
+
+    Checks the `confirm` flag and consults the `OptionsManager` for any relevant
+    flags that may override the need for confirmation, such as `--never-prompt`,
+    `--force-confirm`, or `--skip-confirm`. The `override_namespace` is checked
+    first for any explicit overrides, followed by the main `namespace` for defaults.
+
+    Args:
+        confirm (bool): The initial confirmation flag (e.g., from a command argument).
+        options (OptionsManager): The options manager to check for override flags.
+        namespace (str): The primary namespace to check for options (default: "root").
+        override_namespace (str): The secondary namespace for overrides (default: "execution").
+
+    Returns:
+        bool: True if the user should be prompted, False if confirmation can be bypassed.
     """
+    never_prompt = options.get("never_prompt", None, override_namespace)
+    if never_prompt is None:
         never_prompt = options.get("never_prompt", False, namespace)
+
+    force_confirm = options.get("force_confirm", None, override_namespace)
+    if force_confirm is None:
         force_confirm = options.get("force_confirm", False, namespace)
+
+    skip_confirm = options.get("skip_confirm", None, override_namespace)
+    if skip_confirm is None:
         skip_confirm = options.get("skip_confirm", False, namespace)
 
     if never_prompt or skip_confirm:
@@ -46,3 +95,38 @@ async def confirm_async(
         validator=yes_no_validator(),
     )
     return answer.upper() == "Y"
+
+
+def rich_text_to_prompt_text(text: Text | str | StyleAndTextTuples) -> StyleAndTextTuples:
+    """Convert a Rich Text object to prompt_toolkit formatted text.
+
+    This function takes a Rich `Text` object (or a string or already formatted text)
+    and converts it in to a list of (style, text) tuples compatible with prompt_toolkit.
+
+    Args:
+        text (Text | str | StyleAndTextTuples): The input text to convert.
+
+    Returns:
+        StyleAndTextTuples: A list of (style, text) tuples for prompt_toolkit.
+    """
+    if isinstance(text, list):
+        if all(isinstance(pair, tuple) and len(pair) == 2 for pair in text):
+            return text
+        raise TypeError("Expected list of (style, text) tuples")
+
+    if isinstance(text, str):
+        text = Text.from_markup(text)
+
+    if not isinstance(text, Text):
+        raise TypeError("Expected str, rich.text.Text, or list of (style, text) tuples")
+
+    console = Console(color_system=None, file=None, width=999, legacy_windows=False)
+    segments = text.render(console)
+
+    prompt_fragments: StyleAndTextTuples = []
+    for segment in segments:
+        style = segment.style or ""
+        string = segment.text
+        if string:
+            prompt_fragments.append((str(style), string))
+    return prompt_fragments

falyx/protocols.py

@@ -1,5 +1,17 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""protocols.py"""
+"""Defines structural protocols for advanced Falyx features.
+
+These runtime-checkable `Protocol` classes specify the expected interfaces for:
+- Factories that asynchronously return actions
+- Argument parsers used in dynamic command execution
+
+Used to support type-safe extensibility and plugin-like behavior without requiring
+explicit base classes.
+
+Protocols:
+- ActionFactoryProtocol: Async callable that returns a coroutine yielding a BaseAction.
+- ArgParserProtocol: Callable that accepts CLI-style args and returns (args, kwargs) tuple.
+"""
 from __future__ import annotations
 
 from typing import Any, Awaitable, Callable, Protocol, runtime_checkable
@@ -16,4 +28,6 @@ class ActionFactoryProtocol(Protocol):
 
 @runtime_checkable
 class ArgParserProtocol(Protocol):
-    def __call__(self, args: list[str]) -> tuple[tuple, dict]: ...
+    def __call__(
+        self, args: list[str]
+    ) -> tuple[tuple, dict[str, Any], dict[str, Any]]: ...

falyx/retry.py

@@ -1,5 +1,22 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""retry.py"""
+"""Implements retry logic for Falyx Actions using configurable retry policies.
+
+This module defines:
+- `RetryPolicy`: A configurable model controlling retry behavior (delay, backoff, jitter).
+- `RetryHandler`: A hook-compatible class that manages retry attempts for failed actions.
+
+Used to automatically retry transient failures in leaf-level `Action` objects
+when marked as retryable. Integrates with the Falyx hook lifecycle via `on_error`.
+
+Supports:
+- Exponential backoff with optional jitter
+- Manual or declarative policy control
+- Per-action retry logging and recovery
+
+Example:
+    handler = RetryHandler(RetryPolicy(max_retries=5, delay=1.0))
+    action.hooks.register(HookType.ON_ERROR, handler.retry_on_error)
+"""
 from __future__ import annotations
 
 import asyncio
@@ -12,7 +29,27 @@ from falyx.logger import logger
 
 
 class RetryPolicy(BaseModel):
-    """RetryPolicy"""
+    """Defines a retry strategy for Falyx `Action` objects.
+
+    This model controls whether an action should be retried on failure, and how:
+    - `max_retries`: Maximum number of retry attempts.
+    - `delay`: Initial wait time before the first retry (in seconds).
+    - `backoff`: Multiplier applied to the delay after each failure (≥ 1.0).
+    - `jitter`: Optional random noise added/subtracted from delay to reduce thundering herd issues.
+    - `enabled`: Whether this policy is currently active.
+
+    Retry is only triggered for leaf-level `Action` instances marked with `is_retryable=True`
+    and registered with an appropriate `RetryHandler`.
+
+    Example:
+        RetryPolicy(max_retries=3, delay=1.0, backoff=2.0, jitter=0.2, enabled=True)
+
+    Use `enable_policy()` to activate the policy after construction.
+
+    See Also:
+        - `RetryHandler`: Executes retry logic based on this configuration.
+        - `HookType.ON_ERROR`: The hook type used to trigger retries.
+    """
 
     max_retries: int = Field(default=3, ge=0)
     delay: float = Field(default=1.0, ge=0.0)
@@ -21,22 +58,35 @@ class RetryPolicy(BaseModel):
     enabled: bool = False
 
     def enable_policy(self) -> None:
-        """
+        """Enable the retry policy."""
-        Enable the retry policy.
-        :return: None
-        """
         self.enabled = True
 
     def is_active(self) -> bool:
-        """
+        """Check if the retry policy is active."""
-        Check if the retry policy is active.
-        :return: True if the retry policy is active, False otherwise.
-        """
         return self.max_retries > 0 and self.enabled
 
 
 class RetryHandler:
-    """RetryHandler class to manage retry policies for actions."""
+    """Executes retry logic for Falyx actions using a provided `RetryPolicy`.
+
+    This class is intended to be registered as an `on_error` hook. It will
+    re-attempt the failed `Action`'s `action` method using the args/kwargs from
+    the failed context, following exponential backoff and optional jitter.
+
+    Only supports retrying leaf `Action` instances (not ChainedAction or ActionGroup)
+    where `is_retryable=True`.
+
+    Attributes:
+        policy (RetryPolicy): The retry configuration controlling timing and limits.
+
+    Example:
+        handler = RetryHandler(RetryPolicy(max_retries=3, delay=1.0, enabled=True))
+        action.hooks.register(HookType.ON_ERROR, handler.retry_on_error)
+
+    Notes:
+        - Retries are not triggered if the policy is disabled or `max_retries=0`.
+        - All retry attempts and final failure are logged automatically.
+    """
 
     def __init__(self, policy: RetryPolicy = RetryPolicy()):
         self.policy = policy
@@ -90,14 +140,18 @@ class RetryHandler:
             sleep_delay = current_delay
             if self.policy.jitter > 0:
                 sleep_delay += random.uniform(-self.policy.jitter, self.policy.jitter)
-
+            logger.debug(
+                "[%s] Error: %s",
+                name,
+                last_error,
+            )
             logger.info(
                 "[%s] Retrying (%s/%s) in %ss due to '%s'...",
                 name,
                 retries_done,
                 self.policy.max_retries,
                 current_delay,
-                last_error,
+                last_error.__class__.__name__,
             )
             await asyncio.sleep(current_delay)
             try:
@@ -109,12 +163,17 @@ class RetryHandler:
             except Exception as retry_error:
                 last_error = retry_error
                 current_delay *= self.policy.backoff
+                logger.debug(
+                    "[%s] Error: %s",
+                    name,
+                    retry_error,
+                )
                 logger.warning(
                     "[%s] Retry attempt %s/%s failed due to '%s'.",
                     name,
                     retries_done,
                     self.policy.max_retries,
-                    retry_error,
+                    retry_error.__class__.__name__,
                 )
 
         context.exception = last_error

falyx/retry_utils.py

@@ -1,5 +1,13 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""retry_utils.py"""
+"""Utilities for enabling retry behavior across Falyx actions.
+
+This module provides a helper to recursively apply a `RetryPolicy` to an action and its
+nested children (e.g. `ChainedAction`, `ActionGroup`), and register the appropriate
+`RetryHandler` to hook into error handling.
+
+Includes:
+- `enable_retries_recursively`: Attaches a retry policy and error hook to all eligible actions.
+"""
 from falyx.action.action import Action
 from falyx.action.base_action import BaseAction
 from falyx.hook_manager import HookType

falyx/routing.py

@@ -0,0 +1,95 @@
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
+"""Routing result models for the Falyx CLI framework.
+
+This module defines the core types used to describe the outcome of namespace
+routing in a `Falyx` application.
+
+It provides:
+
+- `RouteKind`, an enum describing the kind of routed target that was reached,
+  such as a leaf command, namespace help, namespace TLDR, namespace menu, or
+  an unknown entry.
+- `RouteResult`, a structured value object that captures the resolved routing
+  state, including the active namespace, invocation context, optional leaf
+  command, remaining argv for command-local parsing, and any suggestions for
+  unresolved input.
+
+These types sit at the boundary between routing and execution. They do not
+perform routing themselves. Instead, they are produced by Falyx routing logic
+and then consumed by help rendering, completion, validation, preview, and
+command dispatch flows.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from falyx.context import InvocationContext
+from falyx.namespace import FalyxNamespace
+
+if TYPE_CHECKING:
+    from falyx.command import Command
+    from falyx.falyx import Falyx
+
+
+class RouteKind(Enum):
+    """Enumerates the possible outcomes of Falyx namespace routing.
+
+    `RouteKind` identifies what the routing layer resolved the current input
+    to, allowing downstream code to decide whether it should execute a command,
+    render namespace help, show TLDR output, display a namespace menu, or
+    surface an unknown-entry message.
+
+    Attributes:
+        COMMAND: Routing reached a leaf command that may be parsed and executed.
+        NAMESPACE_MENU: Routing stopped at a namespace menu target.
+        NAMESPACE_HELP: Routing resolved to namespace help output.
+        NAMESPACE_TLDR: Routing resolved to namespace TLDR output.
+        UNKNOWN: Routing failed to resolve the requested entry.
+    """
+
+    COMMAND = "command"
+    NAMESPACE_MENU = "namespace_menu"
+    NAMESPACE_HELP = "namespace_help"
+    NAMESPACE_TLDR = "namespace_tldr"
+    UNKNOWN = "unknown"
+
+
+@dataclass(slots=True)
+class RouteResult:
+    """Represents the resolved output of a Falyx routing operation.
+
+    `RouteResult` captures the full state needed after namespace resolution
+    completes and before command execution or help rendering begins. It records
+    what kind of target was reached, where routing ended, the invocation path
+    used to reach it, and any leaf-command metadata needed for downstream
+    parsing.
+
+    This model is used by Falyx execution, help, preview, completion, and
+    validation flows to make routing decisions explicit and easy to inspect.
+
+    Attributes:
+        kind: The type of routed result that was resolved.
+        namespace: The `Falyx` namespace where routing ended.
+        context: Invocation context describing the routed path and current mode.
+        command: Resolved leaf command, if routing ended at a command.
+        namespace_entry: Resolved namespace entry, if the route corresponds to a
+            specific nested namespace.
+        leaf_argv: Remaining argv that should be delegated to the resolved
+            command's local parser.
+        current_head: The current head token that routing is evaluating, used for
+            generating suggestions.
+        suggestions: Suggested entry names for unresolved input.
+        is_preview: Whether the routed invocation is in preview mode.
+    """
+
+    kind: RouteKind
+    namespace: "Falyx"
+    context: InvocationContext
+    command: "Command | None" = None
+    namespace_entry: FalyxNamespace | None = None
+    leaf_argv: list[str] = field(default_factory=list)
+    current_head: str = ""
+    suggestions: list[str] = field(default_factory=list)
+    is_preview: bool = False

falyx/selection.py

@@ -1,5 +1,16 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""selection.py"""
+"""Provides interactive selection utilities for Falyx CLI actions.
+
+This module defines `SelectionOption` objects, selection maps, and rich-powered
+rendering functions to build interactive selection prompts using `prompt_toolkit`.
+It supports:
+- Grid-based and dictionary-based selection menus
+- Index- or key-driven multi-select prompts
+- Formatted Rich tables for CLI visual menus
+- Cancel keys, defaults, and duplication control
+
+Used by `SelectionAction` and other prompt-driven workflows within Falyx.
+"""
 from dataclasses import dataclass
 from typing import Any, Callable, KeysView, Sequence
 
@@ -9,6 +20,7 @@ from rich.markup import escape
 from rich.table import Table
 
 from falyx.console import console
+from falyx.prompt_utils import prompt_session_context, rich_text_to_prompt_text
 from falyx.themes import OneColors
 from falyx.utils import CaseInsensitiveDict, chunks
 from falyx.validators import MultiIndexValidator, MultiKeyValidator
@@ -33,9 +45,7 @@ class SelectionOption:
 
 
 class SelectionOptionMap(CaseInsensitiveDict):
-    """
+    """Manages selection options including validation and reserved key protection."""
-    Manages selection options including validation and reserved key protection.
-    """
 
     RESERVED_KEYS: set[str] = set()
 
@@ -105,6 +115,7 @@ def render_table_base(
     highlight: bool = True,
     column_names: Sequence[str] | None = None,
 ) -> Table:
+    """Render the base table for selection prompts."""
     table = Table(
         title=title,
         caption=caption,
@@ -275,13 +286,26 @@ async def prompt_for_index(
     allow_duplicates: bool = False,
     cancel_key: str = "",
 ) -> int | list[int]:
+    """Prompt the user to select an index from a table of options. Return the selected index."""
     prompt_session = prompt_session or PromptSession()
 
     if show_table:
         console.print(table, justify="center")
 
-    selection = await prompt_session.prompt_async(
+    number_selections_str = (
-        message=prompt_message,
+        f"{number_selections} " if isinstance(number_selections, int) else ""
+    )
+
+    plural = "s" if number_selections != 1 else ""
+    placeholder = (
+        f"Enter {number_selections_str}selection{plural} separated by '{separator}'"
+        if number_selections != 1
+        else "Enter selection"
+    )
+
+    with prompt_session_context(prompt_session) as session:
+        selection = await session.prompt_async(
+            message=rich_text_to_prompt_text(prompt_message),
             validator=MultiIndexValidator(
                 min_index,
                 max_index,
@@ -291,6 +315,7 @@ async def prompt_for_index(
                 cancel_key,
             ),
             default=default_selection,
+            placeholder=placeholder,
         )
 
     if selection.strip() == cancel_key:
@@ -319,12 +344,25 @@ async def prompt_for_selection(
     if show_table:
         console.print(table, justify="center")
 
-    selected = await prompt_session.prompt_async(
+    number_selections_str = (
-        message=prompt_message,
+        f"{number_selections} " if isinstance(number_selections, int) else ""
+    )
+
+    plural = "s" if number_selections != 1 else ""
+    placeholder = (
+        f"Enter {number_selections_str}selection{plural} separated by '{separator}'"
+        if number_selections != 1
+        else "Enter selection"
+    )
+
+    with prompt_session_context(prompt_session) as session:
+        selected = await session.prompt_async(
+            message=rich_text_to_prompt_text(prompt_message),
             validator=MultiKeyValidator(
                 keys, number_selections, separator, allow_duplicates, cancel_key
             ),
             default=default_selection,
+            placeholder=placeholder,
         )
 
     if selected.strip() == cancel_key:

falyx/signals.py

@@ -1,5 +1,20 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""signals.py"""
+"""Defines flow control signals used internally by the Falyx CLI framework.
+
+These signals are raised to interrupt or redirect CLI execution flow
+(e.g., returning to a menu, quitting, or displaying help) without
+being treated as traditional exceptions.
+
+All signals inherit from `FlowSignal`, which is a subclass of `BaseException`
+to ensure they bypass standard `except Exception` blocks.
+
+Signals:
+- BreakChainSignal: Exit a chained action early.
+- QuitSignal: Terminate the CLI session.
+- BackSignal: Return to the previous menu or caller.
+- CancelSignal: Cancel the current operation.
+- HelpSignal: Trigger help output in interactive flows.
+"""
 
 
 class FlowSignal(BaseException):

falyx/spinner_manager.py

@@ -0,0 +1,245 @@
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
+"""Centralized spinner rendering for Falyx CLI.
+
+This module provides the `SpinnerManager` class, which manages a collection of
+Rich spinners that can be displayed concurrently during long-running tasks.
+
+Key Features:
+    • Automatic lifecycle management:
+        - Starts a single Rich `Live` loop when the first spinner is added.
+        - Stops and clears the display when the last spinner is removed.
+    • Thread/async-safe start logic via a lightweight lock to prevent
+      duplicate Live loops from being launched.
+    • Supports multiple spinners running simultaneously, each with its own
+      text, style, type, and speed.
+    • Integrates with Falyx's OptionsManager so actions and commands can
+      declaratively request spinners without directly managing terminal state.
+
+Classes:
+    SpinnerData:
+        Lightweight container for individual spinner settings (message,
+        type, style, speed) and its underlying Rich `Spinner` object.
+    SpinnerManager:
+        Manages all active spinners, handles Live rendering, and provides
+        methods to add, update, and remove spinners.
+
+Example:
+    ```python
+    >>> manager = SpinnerManager()
+    >>> await manager.add("build", "Building project…", spinner_type="dots")
+    >>> await manager.add("deploy", "Deploying to AWS…", spinner_type="earth")
+    # Both spinners animate in one unified Live panel
+    >>> manager.remove("build")
+    >>> manager.remove("deploy")
+    ```
+
+Design Notes:
+    • SpinnerManager should only create **one** Live loop at a time.
+    • When no spinners remain, the Live panel is cleared (`transient=True`)
+      so the CLI output returns to a clean state.
+    • Hooks in `falyx.hooks` (spinner_before_hook / spinner_teardown_hook)
+      call into this manager automatically when `spinner=True` is set on
+      an Action or Command.
+"""
+
+import asyncio
+
+from rich.console import Group
+from rich.live import Live
+from rich.spinner import Spinner
+
+from falyx.console import console
+from falyx.logger import logger
+from falyx.themes import OneColors
+
+
+class SpinnerData:
+    """Holds the configuration and Rich spinner object for a single task.
+
+    This class is a lightweight container for spinner metadata, storing the
+    message text, spinner type, style, and speed. It also initializes the
+    corresponding Rich `Spinner` instance used by `SpinnerManager` for
+    rendering.
+
+    Attributes:
+        text (str): The message displayed next to the spinner.
+        spinner_type (str): The Rich spinner preset to use (e.g., "dots",
+            "bouncingBall", "earth").
+        spinner_style (str): Rich color/style for the spinner animation.
+        spinner (Spinner): The instantiated Rich spinner object.
+
+    Example:
+        ```
+        >>> data = SpinnerData("Deploying...", spinner_type="earth",
+        ...                    spinner_style="cyan", spinner_speed=1.0)
+        >>> data.spinner
+        <rich.spinner.Spinner object ...>
+        ```
+    """
+
+    def __init__(
+        self, text: str, spinner_type: str, spinner_style: str, spinner_speed: float
+    ):
+        """Initialize a spinner with text, type, style, and speed."""
+        self.text = text
+        self.spinner_type = spinner_type
+        self.spinner_style = spinner_style
+        self.spinner = Spinner(
+            spinner_type, text=text, style=spinner_style, speed=spinner_speed
+        )
+
+
+class SpinnerManager:
+    """Manages multiple Rich spinners and handles their terminal rendering.
+
+    SpinnerManager maintains a registry of active spinners and a single
+    Rich `Live` display loop to render them. When the first spinner is added,
+    the Live loop starts automatically. When the last spinner is removed,
+    the Live loop stops and the panel clears (via `transient=True`).
+
+    This class is designed for integration with Falyx's `OptionsManager`
+    so any Action or Command can declaratively register spinners without
+    directly controlling terminal state.
+
+    Key Behaviors:
+        • Starts exactly one `Live` loop, protected by a start lock to prevent
+          duplicate launches in async/threaded contexts.
+        • Supports multiple simultaneous spinners, each with independent
+          text, style, and type.
+        • Clears the display when all spinners are removed.
+
+    Attributes:
+        console (Console): The Rich console used for rendering.
+        _spinners (dict[str, SpinnerData]): Internal store of active spinners.
+        _task (asyncio.Task | None): The running Live loop task, if any.
+        _running (bool): Indicates if the Live loop is currently active.
+
+    Example:
+        ```
+        >>> manager = SpinnerManager()
+        >>> await manager.add("build", "Building project…")
+        >>> await manager.add("deploy", "Deploying services…", spinner_type="earth")
+        >>> manager.remove("build")
+        >>> manager.remove("deploy")
+        ```
+    """
+
+    def __init__(self) -> None:
+        """Initialize the SpinnerManager with an empty spinner registry."""
+        self.console = console
+        self._spinners: dict[str, SpinnerData] = {}
+        self._task: asyncio.Task | None = None
+        self._running: bool = False
+
+        self._lock = asyncio.Lock()
+
+    async def add(
+        self,
+        name: str,
+        text: str,
+        spinner_type: str = "dots",
+        spinner_style: str = OneColors.CYAN,
+        spinner_speed: float = 1.0,
+    ):
+        """Add a new spinner and start the Live loop if not already running."""
+        self._spinners[name] = SpinnerData(
+            text=text,
+            spinner_type=spinner_type,
+            spinner_style=spinner_style,
+            spinner_speed=spinner_speed,
+        )
+        async with self._lock:
+            if not self._running:
+                logger.debug("[%s] Starting spinner manager Live loop.", name)
+                await self._start_live()
+
+    def update(
+        self,
+        name: str,
+        text: str | None = None,
+        spinner_type: str | None = None,
+        spinner_style: str | None = None,
+    ):
+        """Update an existing spinner's message, style, or type."""
+        if name in self._spinners:
+            data = self._spinners[name]
+            if text:
+                data.text = text
+                data.spinner.text = text
+            if spinner_style:
+                data.spinner_style = spinner_style
+                data.spinner.style = spinner_style
+            if spinner_type:
+                data.spinner_type = spinner_type
+                data.spinner = Spinner(spinner_type, text=data.text)
+
+    async def remove(self, name: str):
+        """Remove a spinner and stop the Live loop if no spinners remain."""
+        self._spinners.pop(name, None)
+        async with self._lock:
+            if not self._spinners:
+                logger.debug("[%s] Stopping spinner manager, no spinners left.", name)
+                if self._task:
+                    self._task.cancel()
+                self._running = False
+
+    async def _start_live(self):
+        """Start the Live rendering loop in the background."""
+        self._running = True
+        self._task = asyncio.create_task(self._live_loop())
+
+    def render_panel(self):
+        """Render all active spinners as a grouped Rich panel."""
+        rows = []
+        for data in self._spinners.values():
+            rows.append(data.spinner)
+        return Group(*rows)
+
+    async def _live_loop(self):
+        """Continuously refresh the spinner display until stopped."""
+        with Live(
+            self.render_panel(),
+            refresh_per_second=12.5,
+            console=self.console,
+            transient=True,
+        ) as live:
+            while self._spinners:
+                live.update(self.render_panel())
+                await asyncio.sleep(0.1)
+
+
+if __name__ == "__main__":
+    spinner_manager = SpinnerManager()
+
+    async def demo():
+        # Add multiple spinners
+        await spinner_manager.add("task1", "Loading configs…")
+        await spinner_manager.add(
+            "task2", "Building containers…", spinner_type="bouncingBall"
+        )
+        await spinner_manager.add("task3", "Deploying services…", spinner_type="earth")
+
+        # Simulate work
+        await asyncio.sleep(2)
+        spinner_manager.update("task1", text="Configs loaded ✅")
+        await asyncio.sleep(1)
+        spinner_manager.remove("task1")
+
+        await spinner_manager.add("task4", "Running Tests...")
+
+        await asyncio.sleep(2)
+        spinner_manager.update("task2", text="Build complete ✅")
+        spinner_manager.remove("task2")
+
+        await asyncio.sleep(1)
+        spinner_manager.update("task3", text="Deployed! 🎉")
+        await asyncio.sleep(1)
+        spinner_manager.remove("task3")
+
+        await asyncio.sleep(5)
+
+        spinner_manager.update("task4", "Tests Complete!")
+        spinner_manager.remove("task4")
+        console.print("Done!")
+
+    asyncio.run(demo())

falyx/tagged_table.py

@@ -1,5 +1,14 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""tagged_table.py"""
+"""Generates a Rich table view of Falyx commands grouped by their tags.
+
+This module defines a utility function for rendering a custom CLI command
+table that organizes commands into groups based on their first tag. It is
+used to visually separate commands in interactive menus for better clarity
+and discoverability.
+
+Functions:
+- build_tagged_table(flx): Returns a `rich.Table` of commands grouped by tag.
+"""
 from collections import defaultdict
 
 from rich import box
@@ -15,19 +24,19 @@ def build_tagged_table(flx: Falyx) -> Table:
 
     # Group commands by first tag
     grouped: dict[str, list[Command]] = defaultdict(list)
-    for cmd in flx.commands.values():
+    for command in flx.commands.values():
-        first_tag = cmd.tags[0] if cmd.tags else "Other"
+        first_tag = command.tags[0] if command.tags else "Other"
-        grouped[first_tag.capitalize()].append(cmd)
+        grouped[first_tag.capitalize()].append(command)
 
     # Add grouped commands to table
     for group_name, commands in grouped.items():
         table.add_row(f"[bold underline]{group_name} Commands[/]")
-        for cmd in commands:
+        for command in commands:
-            table.add_row(f"[{cmd.key}] [{cmd.style}]{cmd.description}")
+            table.add_row(f"[{command.key}] [{command.style}]{command.description}")
         table.add_row("")
 
     # Add bottom row
-    for row in flx.get_bottom_row():
+    for row in flx._get_bottom_row():
         table.add_row(row)
 
     return table

falyx/themes/__init__.py

@@ -1,7 +1,6 @@
-"""
+"""Falyx CLI Framework
-Falyx CLI Framework
 
-Copyright (c) 2025 rtj.dev LLC.
+Copyright (c) 2026 rtj.dev LLC.
 Licensed under the MIT License. See LICENSE file for details.
 """
 

falyx/themes/colors.py

@@ -1,7 +1,5 @@
-"""
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-colors.py
+"""A Python module that integrates the Nord color palette with the Rich library.
-
-A Python module that integrates the Nord color palette with the Rich library.
 It defines a metaclass-based NordColors class allowing dynamic attribute lookups
 (e.g., NORD12bu -> "#D08770 bold underline") and provides a comprehensive Nord-based
 Theme that customizes Rich's default styles.
@@ -27,8 +25,7 @@ from rich.theme import Theme
 
 
 class ColorsMeta(type):
-    """
+    """A metaclass that catches attribute lookups like `NORD12buidrs` or `ORANGE_b` and returns
-    A metaclass that catches attribute lookups like `NORD12buidrs` or `ORANGE_b` and returns
     a string combining the base color + bold/italic/underline/dim/reverse/strike flags.
 
     The color values are required to be uppercase with optional underscores and digits,
@@ -153,8 +150,7 @@ class OneColors(metaclass=ColorsMeta):
 
 
 class NordColors(metaclass=ColorsMeta):
-    """
+    """Defines the Nord color palette as class attributes.
-    Defines the Nord color palette as class attributes.
 
     Each color is labeled by its canonical Nord name (NORD0-NORD15)
     and also has useful aliases grouped by theme:
@@ -213,8 +209,7 @@ class NordColors(metaclass=ColorsMeta):
 
     @classmethod
     def as_dict(cls):
-        """
+        """Returns a dictionary mapping every NORD* attribute
-        Returns a dictionary mapping every NORD* attribute
         (e.g. 'NORD0') to its hex code.
         """
         return {
@@ -225,8 +220,7 @@ class NordColors(metaclass=ColorsMeta):
 
     @classmethod
     def aliases(cls):
-        """
+        """Returns a dictionary of *all* other aliases
-        Returns a dictionary of *all* other aliases
         (Polar Night, Snow Storm, Frost, Aurora).
         """
         skip_prefixes = ("NORD", "__")
@@ -463,9 +457,7 @@ NORD_THEME_STYLES: dict[str, Style] = {
 
 
 def get_nord_theme() -> Theme:
-    """
+    """Returns a Rich Theme for the Nord color palette."""
-    Returns a Rich Theme for the Nord color palette.
-    """
     return Theme(NORD_THEME_STYLES)
 
 

falyx/utils.py

@@ -1,5 +1,20 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""utils.py"""
+"""General-purpose utilities and helpers for the Falyx CLI framework.
+
+This module includes asynchronous wrappers, logging setup, formatting utilities,
+and small type-safe enhancements such as `CaseInsensitiveDict` and coroutine enforcement.
+
+Features:
+- `ensure_async`: Wraps sync functions as async coroutines.
+- `chunks`: Splits an iterable into fixed-size chunks.
+- `CaseInsensitiveDict`: Dict subclass with case-insensitive string keys.
+- `setup_logging`: Configures Rich or JSON logging based on environment or container detection.
+- `get_program_invocation`: Returns the recommended CLI command to invoke the program.
+- `running_in_container`: Detects if the process is running inside a container.
+
+These utilities support consistent behavior across CLI rendering, logging,
+command parsing, and compatibility layers.
+"""
 from __future__ import annotations
 
 import functools
@@ -14,6 +29,8 @@ from typing import Any, Awaitable, Callable, TypeVar
 import pythonjsonlogger.json
 from rich.logging import RichHandler
 
+from falyx.console import console
+
 T = TypeVar("T")
 
 
@@ -112,8 +129,7 @@ def setup_logging(
     file_log_level: int = logging.DEBUG,
     console_log_level: int = logging.WARNING,
 ):
-    """
+    """Configure logging for Falyx with support for both CLI-friendly and structured
-    Configure logging for Falyx with support for both CLI-friendly and structured
     JSON output.
 
     This function sets up separate logging handlers for console and file output,
@@ -164,6 +180,7 @@ def setup_logging(
 
     if mode == "cli":
         console_handler: RichHandler | logging.StreamHandler = RichHandler(
+            console=console,
             rich_tracebacks=True,
             show_time=True,
             show_level=True,

falyx/validators.py

@@ -1,9 +1,86 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+# Falyx CLI Framework — (c) 2026 rtj.dev LLC — MIT Licensed
-"""validators.py"""
+"""Input validators for use with Prompt Toolkit and interactive Falyx CLI workflows.
-from typing import KeysView, Sequence
+
+This module defines reusable `Validator` instances and subclasses that enforce valid
+user input during prompts—especially for selection actions, confirmations, and
+argument parsing.
+
+Included Validators:
+- CommandValidator: Validates if the input matches a known command.
+- int_range_validator: Enforces numeric input within a range.
+- key_validator: Ensures the entered value matches a valid selection key.
+- yes_no_validator: Restricts input to 'Y' or 'N'.
+- word_validator / words_validator: Accepts specific valid words (case-insensitive).
+- MultiIndexValidator: Validates numeric list input (e.g. "1,2,3").
+- MultiKeyValidator: Validates string key list input (e.g. "A,B,C").
+
+These validators integrate directly into `PromptSession.prompt_async()` to
+enforce correctness and provide helpful error messages.
+"""
+from typing import TYPE_CHECKING, KeysView, Sequence
 
 from prompt_toolkit.validation import ValidationError, Validator
 
+from falyx.routing import RouteKind
+
+if TYPE_CHECKING:
+    from falyx.falyx import Falyx
+
+
+class CommandValidator(Validator):
+    """Validator to check if the input is a valid command."""
+
+    def __init__(self, falyx: "Falyx", error_message: str) -> None:
+        super().__init__()
+        self.falyx = falyx
+        self.error_message = error_message
+
+    def validate(self, document) -> None:
+        if not document.text:
+            raise ValidationError(
+                message=self.error_message,
+                cursor_position=len(document.text),
+            )
+
+    async def validate_async(self, document) -> None:
+        text = document.text
+        if not text:
+            raise ValidationError(
+                message=self.error_message,
+                cursor_position=len(text),
+            )
+        route, _, __, ___ = await self.falyx.prepare_route(text, from_validate=True)
+        if not route:
+            raise ValidationError(
+                message=self.error_message,
+                cursor_position=len(text),
+            )
+        if route.is_preview and route.command is None:
+            raise ValidationError(
+                message=self.error_message,
+                cursor_position=len(text),
+            )
+        elif route.is_preview:
+            return None
+        if route.kind in {
+            RouteKind.NAMESPACE_MENU,
+            RouteKind.NAMESPACE_HELP,
+            RouteKind.NAMESPACE_TLDR,
+        }:
+            return None
+        if route.kind is RouteKind.COMMAND and route.command is None:
+            raise ValidationError(
+                message=self.error_message,
+                cursor_position=len(text),
+            )
+        elif route.kind is RouteKind.COMMAND:
+            return None
+        if route.kind is RouteKind.UNKNOWN:
+            raise ValidationError(
+                message=self.error_message,
+                cursor_position=len(text),
+            )
+
 
 def int_range_validator(minimum: int, maximum: int) -> Validator:
     """Validator for integer ranges."""
@@ -65,6 +142,10 @@ def words_validator(
 
 def word_validator(word: str) -> Validator:
     """Validator for specific word inputs."""
+    if word.upper() == "N":
+        raise ValueError(
+            "The word 'N' is reserved for yes/no validation. Use yes_no_validator instead."
+        )
 
     def validate(text: str) -> bool:
         if text.upper().strip() == "N":
@@ -75,6 +156,8 @@ def word_validator(word: str) -> Validator:
 
 
 class MultiIndexValidator(Validator):
+    """Validator for multiple index selections (e.g. '1,2,3')."""
+
     def __init__(
         self,
         minimum: int,
@@ -125,6 +208,8 @@ class MultiIndexValidator(Validator):
 
 
 class MultiKeyValidator(Validator):
+    """Validator for multiple key selections (e.g. 'A,B,C')."""
+
     def __init__(
         self,
         keys: Sequence[str] | KeysView[str],

falyx/version.py

@@ -1 +1 @@
-__version__ = "0.1.62"
+__version__ = "0.2.0"

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "falyx"
-version = "0.1.62"
+version = "0.2.0"
 description = "Reliable and introspectable async CLI action framework."
 authors = ["Roland Thomas Jr <roland@rtj.dev>"]
 license = "MIT"
@@ -10,7 +10,7 @@ packages = [{ include = "falyx" }]
 [tool.poetry.dependencies]
 python = ">=3.10"
 prompt_toolkit = "^3.0"
-rich = "^13.0"
+rich = "^14.0"
 pydantic = "^2.0"
 python-json-logger = "^3.3.0"
 toml = "^0.10"

tests/test_actions/test_action_basic.py

@@ -1,6 +1,12 @@
 import pytest
 
-from falyx.action import Action, ChainedAction, FallbackAction, LiteralInputAction
+from falyx.action import (
+    Action,
+    ActionGroup,
+    ChainedAction,
+    FallbackAction,
+    LiteralInputAction,
+)
 from falyx.context import ExecutionContext
 from falyx.execution_registry import ExecutionRegistry as er
 
@@ -38,14 +44,13 @@ async def test_action_async_callable():
     action = Action("test_action", async_callable)
     result = await action()
     assert result == "Hello, World!"
-    print(action)
     assert (
         str(action)
-        == "Action(name='test_action', action=async_callable, retry=False, rollback=False)"
+        == "Action(name='test_action', action=async_callable, args=(), kwargs={}, retry=False, rollback=False)"
     )
     assert (
         repr(action)
-        == "Action(name='test_action', action=async_callable, retry=False, rollback=False)"
+        == "Action(name='test_action', action=async_callable, args=(), kwargs={}, retry=False, rollback=False)"
     )
 
 
@@ -60,11 +65,12 @@ async def test_chained_action():
         return_list=True,
     )
 
+    print(chain)
     result = await chain()
     assert result == [1, 2]
     assert (
         str(chain)
-        == "ChainedAction(name='Simple Chain', actions=['one', 'two'], auto_inject=False, return_list=True)"
+        == "ChainedAction(name=Simple Chain, actions=['one', 'two'], args=(), kwargs={}, auto_inject=False, return_list=True)"
     )
 
 
@@ -73,17 +79,17 @@ async def test_action_group():
     """Test if ActionGroup can be created and used."""
     action1 = Action("one", lambda: 1)
     action2 = Action("two", lambda: 2)
-    group = ChainedAction(
+    group = ActionGroup(
         name="Simple Group",
         actions=[action1, action2],
-        return_list=True,
     )
 
+    print(group)
     result = await group()
-    assert result == [1, 2]
+    assert result == [("one", 1), ("two", 2)]
     assert (
         str(group)
-        == "ChainedAction(name='Simple Group', actions=['one', 'two'], auto_inject=False, return_list=True)"
+        == "ActionGroup(name=Simple Group, actions=['one', 'two'], args=(), kwargs={}, inject_last_result=False, inject_into=last_result)"
     )
 
 

tests/test_actions/test_action_types.py

@@ -0,0 +1,145 @@
+import pytest
+
+from falyx.action.action_types import ConfirmType, FileType, SelectionReturnType
+
+
+def test_file_type_enum():
+    """Test if the FileType enum has all expected members."""
+    assert FileType.TEXT.value == "text"
+    assert FileType.PATH.value == "path"
+    assert FileType.JSON.value == "json"
+    assert FileType.TOML.value == "toml"
+    assert FileType.YAML.value == "yaml"
+    assert FileType.CSV.value == "csv"
+    assert FileType.TSV.value == "tsv"
+    assert FileType.XML.value == "xml"
+
+    assert str(FileType.TEXT) == "text"
+
+
+def test_file_type_choices():
+    """Test if the FileType choices method returns all enum members."""
+    choices = FileType.choices()
+    assert len(choices) == 8
+    assert all(isinstance(choice, FileType) for choice in choices)
+
+
+def test_file_type_missing():
+    """Test if the _missing_ method raises ValueError for invalid values."""
+    with pytest.raises(ValueError, match="Invalid FileType: 'invalid'"):
+        FileType._missing_("invalid")
+
+    with pytest.raises(ValueError, match="Invalid FileType: 123"):
+        FileType._missing_(123)
+
+
+def test_file_type_aliases():
+    """Test if the _get_alias method returns correct aliases."""
+    assert FileType._get_alias("file") == "path"
+    assert FileType._get_alias("filepath") == "path"
+    assert FileType._get_alias("unknown") == "unknown"
+
+
+def test_file_type_missing_aliases():
+    """Test if the _missing_ method handles aliases correctly."""
+    assert FileType._missing_("file") == FileType.PATH
+    assert FileType._missing_("filepath") == FileType.PATH
+
+    with pytest.raises(ValueError, match="Invalid FileType: 'unknown'"):
+        FileType._missing_("unknown")
+
+
+def test_confirm_type_enum():
+    """Test if the ConfirmType enum has all expected members."""
+    assert ConfirmType.YES_NO.value == "yes_no"
+    assert ConfirmType.YES_CANCEL.value == "yes_cancel"
+    assert ConfirmType.YES_NO_CANCEL.value == "yes_no_cancel"
+    assert ConfirmType.TYPE_WORD.value == "type_word"
+    assert ConfirmType.TYPE_WORD_CANCEL.value == "type_word_cancel"
+    assert ConfirmType.OK_CANCEL.value == "ok_cancel"
+    assert ConfirmType.ACKNOWLEDGE.value == "acknowledge"
+
+    assert str(ConfirmType.YES_NO) == "yes_no"
+
+
+def test_confirm_type_choices():
+    """Test if the ConfirmType choices method returns all enum members."""
+    choices = ConfirmType.choices()
+    assert len(choices) == 7
+    assert all(isinstance(choice, ConfirmType) for choice in choices)
+
+
+def test_confirm_type_missing():
+    """Test if the _missing_ method raises ValueError for invalid values."""
+    with pytest.raises(ValueError, match="Invalid ConfirmType: 'invalid'"):
+        ConfirmType._missing_("invalid")
+
+    with pytest.raises(ValueError, match="Invalid ConfirmType: 123"):
+        ConfirmType._missing_(123)
+
+
+def test_confirm_type_aliases():
+    """Test if the _get_alias method returns correct aliases."""
+    assert ConfirmType._get_alias("yes") == "yes_no"
+    assert ConfirmType._get_alias("ok") == "ok_cancel"
+    assert ConfirmType._get_alias("type") == "type_word"
+    assert ConfirmType._get_alias("word") == "type_word"
+    assert ConfirmType._get_alias("word_cancel") == "type_word_cancel"
+    assert ConfirmType._get_alias("ack") == "acknowledge"
+
+
+def test_confirm_type_missing_aliases():
+    """Test if the _missing_ method handles aliases correctly."""
+    assert ConfirmType("yes") == ConfirmType.YES_NO
+    assert ConfirmType("ok") == ConfirmType.OK_CANCEL
+    assert ConfirmType("word") == ConfirmType.TYPE_WORD
+    assert ConfirmType("ack") == ConfirmType.ACKNOWLEDGE
+
+    with pytest.raises(ValueError, match="Invalid ConfirmType: 'unknown'"):
+        ConfirmType._missing_("unknown")
+
+
+def test_selection_return_type_enum():
+    """Test if the SelectionReturnType enum has all expected members."""
+    assert SelectionReturnType.KEY.value == "key"
+    assert SelectionReturnType.VALUE.value == "value"
+    assert SelectionReturnType.DESCRIPTION.value == "description"
+    assert SelectionReturnType.DESCRIPTION_VALUE.value == "description_value"
+    assert SelectionReturnType.ITEMS.value == "items"
+
+    assert str(SelectionReturnType.KEY) == "key"
+
+
+def test_selection_return_type_choices():
+    """Test if the SelectionReturnType choices method returns all enum members."""
+    choices = SelectionReturnType.choices()
+    assert len(choices) == 5
+    assert all(isinstance(choice, SelectionReturnType) for choice in choices)
+
+
+def test_selection_return_type_missing():
+    """Test if the _missing_ method raises ValueError for invalid values."""
+    with pytest.raises(ValueError, match="Invalid SelectionReturnType: 'invalid'"):
+        SelectionReturnType._missing_("invalid")
+
+    with pytest.raises(ValueError, match="Invalid SelectionReturnType: 123"):
+        SelectionReturnType._missing_(123)
+
+
+def test_selection_return_type_aliases():
+    """Test if the _get_alias method returns correct aliases."""
+    assert SelectionReturnType._get_alias("desc") == "description"
+    assert SelectionReturnType._get_alias("desc_value") == "description_value"
+    assert SelectionReturnType._get_alias("unknown") == "unknown"
+
+
+def test_selection_return_type_missing_aliases():
+    """Test if the _missing_ method handles aliases correctly."""
+    assert SelectionReturnType._missing_("desc") == SelectionReturnType.DESCRIPTION
+    assert (
+        SelectionReturnType._missing_("desc_value")
+        == SelectionReturnType.DESCRIPTION_VALUE
+    )
+
+    with pytest.raises(ValueError, match="Invalid SelectionReturnType: 'unknown'"):
+        SelectionReturnType._missing_("unknown")

tests/test_actions/test_confirm_action.py

@@ -0,0 +1,94 @@
+import pytest
+
+from falyx.action import ConfirmAction
+
+
+@pytest.mark.asyncio
+async def test_confirm_action_yes_no():
+    action = ConfirmAction(
+        name="test",
+        prompt_message="Are you sure?",
+        never_prompt=True,
+        confirm_type="yes_no",
+    )
+
+    result = await action()
+    assert result is True
+
+
+@pytest.mark.asyncio
+async def test_confirm_action_yes_cancel():
+    action = ConfirmAction(
+        name="test",
+        prompt_message="Are you sure?",
+        never_prompt=True,
+        confirm_type="yes_cancel",
+    )
+
+    result = await action()
+    assert result is True
+
+
+@pytest.mark.asyncio
+async def test_confirm_action_yes_no_cancel():
+    action = ConfirmAction(
+        name="test",
+        prompt_message="Are you sure?",
+        never_prompt=True,
+        confirm_type="yes_no_cancel",
+    )
+
+    result = await action()
+    assert result is True
+
+
+@pytest.mark.asyncio
+async def test_confirm_action_type_word():
+    action = ConfirmAction(
+        name="test",
+        prompt_message="Are you sure?",
+        never_prompt=True,
+        confirm_type="type_word",
+    )
+
+    result = await action()
+    assert result is True
+
+
+@pytest.mark.asyncio
+async def test_confirm_action_type_word_cancel():
+    action = ConfirmAction(
+        name="test",
+        prompt_message="Are you sure?",
+        never_prompt=True,
+        confirm_type="type_word_cancel",
+    )
+
+    result = await action()
+    assert result is True
+
+
+@pytest.mark.asyncio
+async def test_confirm_action_ok_cancel():
+    action = ConfirmAction(
+        name="test",
+        prompt_message="Are you sure?",
+        never_prompt=True,
+        confirm_type="ok_cancel",
+    )
+
+    result = await action()
+    assert result is True
+
+
+@pytest.mark.asyncio
+async def test_confirm_action_acknowledge():
+    action = ConfirmAction(
+        name="test",
+        prompt_message="Are you sure?",
+        never_prompt=True,
+        confirm_type="acknowledge",
+    )
+
+    result = await action()
+    assert result is True

tests/test_actions/test_load_file_action.py

@@ -0,0 +1,100 @@
+import pytest
+from rich.text import Text
+
+from falyx.action import LoadFileAction
+from falyx.console import console as falyx_console
+
+
+@pytest.mark.asyncio
+async def test_load_json_file_action(tmp_path):
+    mock_data = '{"key": "value"}'
+    file = tmp_path / "test.json"
+    file.write_text(mock_data)
+    action = LoadFileAction(name="load-file", file_path=file, file_type="json")
+    result = await action()
+    assert result == {"key": "value"}
+
+
+@pytest.mark.asyncio
+async def test_load_yaml_file_action(tmp_path):
+    mock_data = "key: value"
+    file = tmp_path / "test.yaml"
+    file.write_text(mock_data)
+    action = LoadFileAction(name="load-file", file_path=file, file_type="yaml")
+    result = await action()
+    assert result == {"key": "value"}
+
+
+@pytest.mark.asyncio
+async def test_load_toml_file_action(tmp_path):
+    mock_data = 'key = "value"'
+    file = tmp_path / "test.toml"
+    file.write_text(mock_data)
+    action = LoadFileAction(name="load-file", file_path=file, file_type="toml")
+    result = await action()
+    assert result == {"key": "value"}
+
+
+@pytest.mark.asyncio
+async def test_load_csv_file_action(tmp_path):
+    mock_data = "key,value\nfoo,bar"
+    file = tmp_path / "test.csv"
+    file.write_text(mock_data)
+    action = LoadFileAction(name="load-file", file_path=file, file_type="csv")
+    result = await action()
+    print(result)
+    assert result == [["key", "value"], ["foo", "bar"]]
+
+
+@pytest.mark.asyncio
+async def test_load_tsv_file_action(tmp_path):
+    mock_data = "key\tvalue\nfoo\tbar"
+    file = tmp_path / "test.tsv"
+    file.write_text(mock_data)
+    action = LoadFileAction(name="load-file", file_path=file, file_type="tsv")
+    result = await action()
+    assert result == [["key", "value"], ["foo", "bar"]]
+
+
+@pytest.mark.asyncio
+async def test_load_file_action_invalid_path():
+    action = LoadFileAction(
+        name="load-file", file_path="non_existent_file.json", file_type="json"
+    )
+    with pytest.raises(FileNotFoundError):
+        await action()
+
+
+@pytest.mark.asyncio
+async def test_load_file_action_invalid_json(tmp_path):
+    invalid_json = '{"key": "value"'  # Missing closing brace
+    file = tmp_path / "invalid.json"
+    file.write_text(invalid_json)
+    action = LoadFileAction(name="load-file", file_path=file, file_type="json")
+    with pytest.raises(ValueError):
+        await action()
+
+
+@pytest.mark.asyncio
+async def test_load_file_action_unsupported_type(tmp_path):
+    file = tmp_path / "test.txt"
+    file.write_text("Just some text")
+    with pytest.raises(ValueError):
+        LoadFileAction(name="load-file", file_path=file, file_type="unsupported")
+
+
+@pytest.mark.asyncio
+async def test_preview_of_load_file_action(tmp_path):
+    mock_data = '{"key": "value"}'
+    file = tmp_path / "test.json"
+    file.write_text(mock_data)
+    action = LoadFileAction(name="load-file", file_path=file, file_type="json")
+    with falyx_console.capture() as capture:
+        await action.preview()
+    captured = Text.from_ansi(capture.get()).plain
+    assert "LoadFileAction" in captured
+    assert "test.json" in captured
+    assert "load-file" in captured
+    assert "JSON" in captured
+    assert "key" in captured
+    assert "value" in captured

tests/test_actions/test_selection_action.py

@@ -0,0 +1,287 @@
+import pytest
+
+from falyx.action import SelectionAction
+from falyx.selection import SelectionOption
+
+
+@pytest.mark.asyncio
+async def test_selection_list_never_prompt_by_value():
+    action = SelectionAction(
+        name="test",
+        selections=["a", "b", "c"],
+        default_selection="b",
+        never_prompt=True,
+    )
+    assert action.never_prompt is True
+    assert action.default_selection == "b"
+
+    result = await action()
+    assert result == "b"
+
+
+@pytest.mark.asyncio
+async def test_selection_list_never_prompt_by_index():
+    action = SelectionAction(
+        name="test",
+        selections=["a", "b", "c"],
+        default_selection="2",
+        never_prompt=True,
+    )
+    assert action.never_prompt is True
+    assert action.default_selection == "2"
+
+    result = await action()
+    assert result == "c"
+
+
+@pytest.mark.asyncio
+async def test_selection_list_never_prompt_by_value_multi_select():
+    action = SelectionAction(
+        name="test",
+        selections=["a", "b", "c"],
+        default_selection=["b", "c"],
+        never_prompt=True,
+        number_selections=2,
+    )
+    assert action.never_prompt is True
+    assert action.default_selection == ["b", "c"]
+
+    result = await action()
+    assert result == ["b", "c"]
+
+
+@pytest.mark.asyncio
+async def test_selection_list_never_prompt_by_index_multi_select():
+    action = SelectionAction(
+        name="test",
+        selections=["a", "b", "c"],
+        default_selection=["1", "2"],
+        never_prompt=True,
+        number_selections=2,
+    )
+    assert action.never_prompt is True
+    assert action.default_selection == ["1", "2"]
+
+    result = await action()
+    assert result == ["b", "c"]
+
+
+@pytest.mark.asyncio
+async def test_selection_prompt_dict_never_prompt():
+    action = SelectionAction(
+        name="test",
+        selections={"a": "Alpha", "b": "Beta", "c": "Gamma"},
+        default_selection="b",
+        never_prompt=True,
+    )
+    assert action.never_prompt is True
+    assert action.default_selection == "b"
+
+    result = await action()
+    assert result == "Beta"
+
+
+@pytest.mark.asyncio
+async def test_selection_prompt_dict_never_prompt_by_value():
+    action = SelectionAction(
+        name="test",
+        selections={"a": "Alpha", "b": "Beta", "c": "Gamma"},
+        default_selection="Beta",
+        never_prompt=True,
+    )
+    assert action.never_prompt is True
+    assert action.default_selection == "Beta"
+
+    result = await action()
+    assert result == "Beta"
+
+
+@pytest.mark.asyncio
+async def test_selection_prompt_dict_never_prompt_by_key():
+    action = SelectionAction(
+        name="test",
+        selections={"a": "Alpha", "b": "Beta", "c": "Gamma"},
+        default_selection="b",
+        never_prompt=True,
+    )
+    assert action.never_prompt is True
+    assert action.default_selection == "b"
+
+    result = await action()
+    assert result == "Beta"
+
+
+@pytest.mark.asyncio
+async def test_selection_prompt_map_never_prompt_by_key():
+    prompt_map = {
+        "a": SelectionOption(description="Alpha", value="Alpha Service"),
+        "b": SelectionOption(description="Beta", value="Beta Service"),
+        "c": SelectionOption(description="Gamma", value="Gamma Service"),
+    }
+    action = SelectionAction(
+        name="test",
+        selections=prompt_map,
+        default_selection="c",
+        never_prompt=True,
+    )
+    assert action.never_prompt is True
+    assert action.default_selection == "c"
+
+    result = await action()
+    assert result == "Gamma Service"
+
+
+@pytest.mark.asyncio
+async def test_selection_prompt_map_never_prompt_by_description():
+    prompt_map = {
+        "a": SelectionOption(description="Alpha", value="Alpha Service"),
+        "b": SelectionOption(description="Beta", value="Beta Service"),
+        "c": SelectionOption(description="Gamma", value="Gamma Service"),
+    }
+    action = SelectionAction(
+        name="test",
+        selections=prompt_map,
+        default_selection="Alpha",
+        never_prompt=True,
+    )
+    assert action.never_prompt is True
+    assert action.default_selection == "Alpha"
+
+    result = await action()
+    assert result == "Alpha Service"
+
+
+@pytest.mark.asyncio
+async def test_selection_prompt_map_never_prompt_by_value():
+    prompt_map = {
+        "a": SelectionOption(description="Alpha", value="Alpha Service"),
+        "b": SelectionOption(description="Beta", value="Beta Service"),
+        "c": SelectionOption(description="Gamma", value="Gamma Service"),
+    }
+    action = SelectionAction(
+        name="test",
+        selections=prompt_map,
+        default_selection="Beta Service",
+        never_prompt=True,
+    )
+    assert action.never_prompt is True
+    assert action.default_selection == "Beta Service"
+
+    result = await action()
+    assert result == "Beta Service"
+
+
+@pytest.mark.asyncio
+async def test_selection_prompt_dict_never_prompt_by_value_multi_select():
+    action = SelectionAction(
+        name="test",
+        selections={"a": "Alpha", "b": "Beta", "c": "Gamma"},
+        default_selection=["Beta", "Gamma"],
+        number_selections=2,
+        never_prompt=True,
+    )
+    assert action.never_prompt is True
+    assert action.default_selection == ["Beta", "Gamma"]
+
+    result = await action()
+    assert result == ["Beta", "Gamma"]
+
+
+@pytest.mark.asyncio
+async def test_selection_prompt_dict_never_prompt_by_key_multi_select():
+    action = SelectionAction(
+        name="test",
+        selections={"a": "Alpha", "b": "Beta", "c": "Gamma"},
+        default_selection=["a", "b"],
+        number_selections=2,
+        never_prompt=True,
+    )
+    assert action.never_prompt is True
+    assert action.default_selection == ["a", "b"]
+
+    result = await action()
+    assert result == ["Alpha", "Beta"]
+
+
+@pytest.mark.asyncio
+async def test_selection_prompt_map_never_prompt_by_key_multi_select():
+    prompt_map = {
+        "a": SelectionOption(description="Alpha", value="Alpha Service"),
+        "b": SelectionOption(description="Beta", value="Beta Service"),
+        "c": SelectionOption(description="Gamma", value="Gamma Service"),
+    }
+    action = SelectionAction(
+        name="test",
+        selections=prompt_map,
+        default_selection=["b", "c"],
+        number_selections=2,
+        never_prompt=True,
+    )
+    assert action.never_prompt is True
+    assert action.default_selection == ["b", "c"]
+
+    result = await action()
+    assert result == ["Beta Service", "Gamma Service"]
+
+
+@pytest.mark.asyncio
+async def test_selection_prompt_map_never_prompt_by_description_multi_select():
+    prompt_map = {
+        "a": SelectionOption(description="Alpha", value="Alpha Service"),
+        "b": SelectionOption(description="Beta", value="Beta Service"),
+        "c": SelectionOption(description="Gamma", value="Gamma Service"),
+    }
+    action = SelectionAction(
+        name="test",
+        selections=prompt_map,
+        default_selection=["Alpha", "Gamma"],
+        number_selections=2,
+        never_prompt=True,
+    )
+    assert action.never_prompt is True
+    assert action.default_selection == ["Alpha", "Gamma"]
+
+    result = await action()
+    assert result == ["Alpha Service", "Gamma Service"]
+
+
+@pytest.mark.asyncio
+async def test_selection_prompt_map_never_prompt_by_value_multi_select():
+    prompt_map = {
+        "a": SelectionOption(description="Alpha", value="Alpha Service"),
+        "b": SelectionOption(description="Beta", value="Beta Service"),
+        "c": SelectionOption(description="Gamma", value="Gamma Service"),
+    }
+    action = SelectionAction(
+        name="test",
+        selections=prompt_map,
+        default_selection=["Beta Service", "Alpha Service"],
+        number_selections=2,
+        never_prompt=True,
+    )
+    assert action.never_prompt is True
+    assert action.default_selection == ["Beta Service", "Alpha Service"]
+
+    result = await action()
+    assert result == ["Beta Service", "Alpha Service"]
+
+
+@pytest.mark.asyncio
+async def test_selection_prompt_map_never_prompt_by_value_wildcard():
+    prompt_map = {
+        "a": SelectionOption(description="Alpha", value="Alpha Service"),
+        "b": SelectionOption(description="Beta", value="Beta Service"),
+        "c": SelectionOption(description="Gamma", value="Gamma Service"),
+    }
+    action = SelectionAction(
+        name="test",
+        selections=prompt_map,
+        default_selection=["Beta Service", "Alpha Service"],
+        number_selections="*",
+        never_prompt=True,
+    )
+    assert action.never_prompt is True
+    assert action.default_selection == ["Beta Service", "Alpha Service"]
+
+    result = await action()
+    assert result == ["Beta Service", "Alpha Service"]

tests/test_command.py

@@ -1,5 +1,6 @@
 # test_command.py
 import pytest
+from pydantic import ValidationError
 
 from falyx.action import Action, BaseIOAction, ChainedAction
 from falyx.command import Command
@@ -53,7 +54,7 @@ def test_command_str():
     print(cmd)
     assert (
         str(cmd)
-        == "Command(key='TEST', description='Test Command' action='Action(name='test_action', action=dummy_action, retry=False, rollback=False)')"
+        == "Command(key='TEST', description='Test Command' action='Action(name='test_action', action=dummy_action, args=(), kwargs={}, retry=False, rollback=False)')"
     )
 
 
@@ -172,3 +173,15 @@ def test_command_bad_action():
     with pytest.raises(TypeError) as exc_info:
         Command(key="TEST", description="Test Command", action="not_callable")
     assert str(exc_info.value) == "Action must be a callable or an instance of BaseAction"
+
+
+def test_command_bad_options_manager():
+    """Test if Command raises an exception when options_manager is not a dict or callable."""
+    with pytest.raises(ValidationError) as exc_info:
+        Command(
+            key="TEST",
+            description="Test Command",
+            action=dummy_action,
+            options_manager="not_a_dict_or_callable",
+        )
+    assert "Input should be an instance of OptionsManager" in str(exc_info.value)

tests/test_completer/test_completer.py

@@ -0,0 +1,305 @@
+import re
+
+import pytest
+from prompt_toolkit.completion import Completion
+from prompt_toolkit.document import Document
+
+from falyx import Falyx
+from falyx.completer import FalyxCompleter
+from falyx.parser import CommandArgumentParser
+
+
+def completion_texts(completions) -> list[str]:
+    return [c.text for c in completions]
+
+
+@pytest.fixture
+def falyx():
+    flx = Falyx()
+
+    run_parser = CommandArgumentParser(
+        command_key="R",
+        command_description="Run Command",
+    )
+    run_parser.add_argument("--tag")
+    run_parser.add_argument("--name")
+
+    flx.add_command(
+        "R",
+        "Run Command",
+        lambda: None,
+        aliases=["RUN"],
+        arg_parser=run_parser,
+    )
+
+    ops = Falyx(program="ops")
+
+    deploy_parser = CommandArgumentParser(
+        command_key="D",
+        command_description="Deploy Command",
+    )
+    deploy_parser.add_argument("--target")
+    deploy_parser.add_argument("--region")
+
+    ops.add_command(
+        "D",
+        "Deploy Command",
+        lambda: None,
+        aliases=["DEPLOY"],
+        arg_parser=deploy_parser,
+    )
+
+    flx.add_submenu(
+        "OPS",
+        "Operations",
+        ops,
+        aliases=["OPERATIONS"],
+    )
+
+    return flx
+
+
+def test_suggest_namespace_entries_root(falyx):
+    completer = FalyxCompleter(falyx)
+
+    completions = completer._suggest_namespace_entries(falyx, "R")
+
+    assert "R" in completions
+    assert "RUN" in completions
+
+    completions = completer._suggest_namespace_entries(falyx, "r")
+
+    assert "r" in completions
+    assert "run" in completions
+
+
+def test_suggest_namespace_entries_submenu(falyx):
+    completer = FalyxCompleter(falyx)
+    ops = falyx.namespaces["OPS"].namespace
+
+    completions = completer._suggest_namespace_entries(ops, "D")
+
+    assert "D" in completions
+    assert "DEPLOY" in completions
+
+
+def test_get_completions_no_input_shows_root_entries(falyx):
+    completer = FalyxCompleter(falyx)
+
+    results = list(completer.get_completions(Document(""), None))
+    texts = completion_texts(results)
+
+    assert any(isinstance(c, Completion) for c in results)
+    assert "R" in texts
+    assert "OPS" in texts
+    assert "X" in texts
+
+
+def test_get_completions_partial_root_entry(falyx):
+    completer = FalyxCompleter(falyx)
+
+    results = list(completer.get_completions(Document("OP"), None))
+    texts = completion_texts(results)
+
+    assert "OPS" in texts
+    assert "OPERATIONS" in texts
+
+
+def test_get_completions_no_match_returns_empty(falyx):
+    completer = FalyxCompleter(falyx)
+
+    assert list(completer.get_completions(Document("Z"), None)) == []
+    assert list(completer.get_completions(Document("OPS Z"), None)) == []
+
+
+def test_get_completions_namespace_boundary_suggests_help_flags(falyx):
+    completer = FalyxCompleter(falyx)
+
+    results = list(completer.get_completions(Document("OPS -"), None))
+    texts = completion_texts(results)
+
+    assert "-h" in texts
+    assert "--help" in texts
+    assert "-T" not in texts
+    assert "--tldr" not in texts
+
+    falyx.add_tldr_example(
+        entry_key="R",
+        usage="",
+        description="This is a TLDR example for the R command.",
+    )
+    results = list(completer.get_completions(Document("-"), None))
+    texts = completion_texts(results)
+
+    assert "-h" in texts
+    assert "--help" in texts
+    assert "-T" in texts
+    assert "--tldr" in texts
+
+
+def test_get_completions_preview_prefix_is_preserved(falyx):
+    completer = FalyxCompleter(falyx)
+
+    results = list(completer.get_completions(Document("?R"), None))
+    texts = completion_texts(results)
+
+    assert any(text.startswith("?R") for text in texts)
+
+
+def test_get_completions_preview_prefix_for_namespace_entries(falyx):
+    completer = FalyxCompleter(falyx)
+
+    results = list(completer.get_completions(Document("?OP"), None))
+    texts = completion_texts(results)
+
+    assert "?OPS" in texts or "?OPERATIONS" in texts
+
+
+def test_get_completions_leaf_command_delegates_flags_to_root_command_parser(
+    falyx, monkeypatch
+):
+    completer = FalyxCompleter(falyx)
+
+    seen = {}
+
+    def fake_suggest_next(args, cursor_at_end_of_token):
+        seen["args"] = list(args)
+        seen["cursor_at_end_of_token"] = cursor_at_end_of_token
+        return ["--tag"]
+
+    monkeypatch.setattr(
+        falyx.commands["R"].arg_parser,
+        "suggest_next",
+        fake_suggest_next,
+    )
+
+    results = list(completer.get_completions(Document("R --t"), None))
+    texts = completion_texts(results)
+
+    assert seen["args"] == ["--t"]
+    assert seen["cursor_at_end_of_token"] is False
+    assert "--tag" in texts
+
+
+def test_get_completions_leaf_command_delegates_flags_to_submenu_command_parser(
+    falyx, monkeypatch
+):
+    completer = FalyxCompleter(falyx)
+    ops = falyx.namespaces["OPS"].namespace
+    deploy = ops.commands["D"]
+
+    seen = {}
+
+    def fake_suggest_next(args, cursor_at_end_of_token):
+        seen["args"] = list(args)
+        seen["cursor_at_end_of_token"] = cursor_at_end_of_token
+        return ["--target"]
+
+    monkeypatch.setattr(
+        deploy.arg_parser,
+        "suggest_next",
+        fake_suggest_next,
+    )
+
+    results = list(completer.get_completions(Document("OPS D --t"), None))
+    texts = completion_texts(results)
+
+    assert seen["args"] == ["--t"]
+    assert seen["cursor_at_end_of_token"] is False
+    assert "--target" in texts
+
+
+def test_get_completions_leaf_command_receives_empty_stub_after_space(falyx, monkeypatch):
+    completer = FalyxCompleter(falyx)
+
+    seen = {}
+
+    def fake_suggest_next(args, cursor_at_end_of_token):
+        seen["args"] = list(args)
+        seen["cursor_at_end_of_token"] = cursor_at_end_of_token
+        return ["--tag", "--name"]
+
+    monkeypatch.setattr(
+        falyx.commands["R"].arg_parser,
+        "suggest_next",
+        fake_suggest_next,
+    )
+
+    results = list(completer.get_completions(Document("R "), None))
+    texts = completion_texts(results)
+
+    assert seen["args"] == []
+    assert seen["cursor_at_end_of_token"] is True
+    assert "--tag" in texts
+    assert "--name" in texts
+
+
+def test_get_completions_bad_input(falyx):
+    completer = FalyxCompleter(falyx)
+
+    results = list(completer.get_completions(Document('R "unclosed quote'), None))
+
+    assert results == []
+
+
+def test_get_completions_exception_handling(falyx, monkeypatch):
+    completer = FalyxCompleter(falyx)
+
+    def boom(*args, **kwargs):
+        raise ZeroDivisionError("boom")
+
+    monkeypatch.setattr(falyx.commands["R"].arg_parser, "suggest_next", boom)
+
+    results = list(completer.get_completions(Document("R --tag"), None))
+
+    assert results == []
+
+
+def test_ensure_quote_wraps_whitespace(falyx):
+    completer = FalyxCompleter(falyx)
+
+    assert completer._ensure_quote("hello world") == '"hello world"'
+    assert completer._ensure_quote("hello") == "hello"
+
+
+def test_command_suggestions_are_case_insensitive(falyx):
+    completer = FalyxCompleter(falyx)
+
+    results = list(completer.get_completions(Document("r"), None))
+    texts = completion_texts(results)
+
+    assert "r" in texts
+    assert "run" in texts
+
+    results = list(completer.get_completions(Document("R"), None))
+    texts = completion_texts(results)
+
+    assert "R" in texts
+    assert "RUN" in texts
+
+
+def test_namespace_suggestions_are_case_insensitive(falyx):
+    completer = FalyxCompleter(falyx)
+
+    results = list(completer.get_completions(Document("op"), None))
+    texts = completion_texts(results)
+
+    assert "ops" in texts
+    assert "operations" in texts
+
+    results = list(completer.get_completions(Document("OP"), None))
+    texts = completion_texts(results)
+
+    assert "OPS" in texts
+    assert "OPERATIONS" in texts
+
+
+def test_command_completions_after_namespace(falyx):
+    completer = FalyxCompleter(falyx)
+
+    results = list(completer.get_completions(Document("OPS D --"), None))
+    texts = completion_texts(results)
+
+    assert "--target" in texts
+    assert "--region" in texts
+    assert "--help" in texts

tests/test_completer/test_lcp_completions.py

@@ -0,0 +1,42 @@
+from types import SimpleNamespace
+
+import pytest
+
+from falyx.completer import FalyxCompleter
+
+
+def completion_texts(completions) -> list[str]:
+    return [c.text for c in completions]
+
+
+def test_lcp_completions():
+    completer = FalyxCompleter(SimpleNamespace())
+    suggestions = ["AETHERWARP", "AETHERZOOM"]
+    stub = "A"
+    completions = list(completer._yield_lcp_completions(suggestions, stub))
+    texts = completion_texts(completions)
+
+    assert "AETHER" in texts
+    assert "AETHERWARP" in texts
+    assert "AETHERZOOM" in texts
+
+
+def test_lcp_completions_space():
+    completer = FalyxCompleter(SimpleNamespace())
+    suggestions = ["London", "New York", "San Francisco"]
+    stub = "N"
+    completions = list(completer._yield_lcp_completions(suggestions, stub))
+    texts = completion_texts(completions)
+    assert '"New York"' in texts
+
+
+def test_lcp_completions_does_not_collapse_flags():
+    completer = FalyxCompleter(SimpleNamespace())
+    suggestions = ["--tag", "--target"]
+    stub = "--t"
+    completions = list(completer._yield_lcp_completions(suggestions, stub))
+    texts = completion_texts(completions)
+
+    assert "--tag" in texts
+    assert "--target" in texts
+    assert "--ta" not in texts

tests/test_execution_option.py

@@ -0,0 +1,30 @@
+import pytest
+
+from falyx.execution_option import ExecutionOption
+
+
+def test_execution_option_accepts_valid_string_values():
+    assert ExecutionOption("summary") == ExecutionOption.SUMMARY
+    assert ExecutionOption("retry") == ExecutionOption.RETRY
+    assert ExecutionOption("confirm") == ExecutionOption.CONFIRM
+
+
+def test_execution_option_rejects_invalid_string():
+    with pytest.raises(ValueError, match="Invalid ExecutionOption: 'invalid'"):
+        ExecutionOption("invalid")
+
+
+def test_execution_option_normalizes_case_and_whitespace():
+    assert ExecutionOption("  SUMMARY  ") == ExecutionOption.SUMMARY
+    assert ExecutionOption("ReTrY") == ExecutionOption.RETRY
+    assert ExecutionOption("\tconfirm\n") == ExecutionOption.CONFIRM
+
+
+def test_execution_option_rejects_non_string():
+    with pytest.raises(ValueError, match="Invalid ExecutionOption: 123"):
+        ExecutionOption(123)
+
+
+def test_execution_option_error_lists_valid_values():
+    with pytest.raises(ValueError, match="Must be one of: summary, retry, confirm"):
+        ExecutionOption("invalid")