cmdx 1.8.0 → 1.9.0

data/docs/basics/context.md

@@ -1,17 +1,10 @@
 # Basics - Context
 
-Task context provides flexible data storage, access, and sharing within task execution. It serves as the primary data container for all task inputs, intermediate results, and outputs.
-
-## Table of Contents
-
-- [Assigning Data](#assigning-data)
-- [Accessing Data](#accessing-data)
-- [Modifying Context](#modifying-context)
-- [Data Sharing](#data-sharing)
+Context is your data container for inputs, intermediate values, and outputs. It makes sharing data between tasks effortless.
 
 ## Assigning Data
 
-Context is automatically populated with all inputs passed to a task. All keys are normalized to symbols for consistent access:
+Context automatically captures all task inputs, normalizing keys to symbols:
 
 ```ruby
 # Direct execution
@@ -21,12 +14,13 @@ CalculateShipping.execute(weight: 2.5, destination: "CA")
 CalculateShipping.new(weight: 2.5, "destination" => "CA")
 ```
 
-> [!IMPORTANT]
-> String keys are automatically converted to symbols. Use symbols for consistency in your code.
+!!! warning "Important"
+
+    String keys convert to symbols automatically. Prefer symbols for consistency.
 
 ## Accessing Data
 
-Context provides multiple access patterns with automatic nil safety:
+Access context data using method notation, hash keys, or safe accessors:
 
 ```ruby
 class CalculateShipping < CMDx::Task
@@ -49,8 +43,9 @@ class CalculateShipping < CMDx::Task
 end
 ```
 
-> [!IMPORTANT]
-> Accessing undefined context attributes returns `nil` instead of raising errors, enabling graceful handling of optional attributes.
+!!! warning "Important"
+
+    Undefined attributes return `nil` instead of raising errors—perfect for optional data.
 
 ## Modifying Context
 
@@ -91,12 +86,13 @@ class CalculateShipping < CMDx::Task
 end
 ```
 
-> [!TIP]
-> Use context for both input values and intermediate results. This creates natural data flow through your task execution pipeline.
+!!! tip
+
+    Use context for both input values and intermediate results. This creates natural data flow through your task execution pipeline.
 
 ## Data Sharing
 
-Context enables seamless data flow between related tasks in complex workflows:
+Share context across tasks for seamless data flow:
 
 ```ruby
 # During execution
@@ -123,8 +119,3 @@ result = CalculateShipping.execute(destination: "New York, NY")
 
 CreateShippingLabel.execute(result)
 ```
-
----
-
-- **Prev:** [Basics - Execution](execution.md)
-- **Next:** [Basics - Chain](chain.md)

data/docs/basics/execution.md

@@ -1,19 +1,10 @@
 # Basics - Execution
 
-Task execution in CMDx provides two distinct methods that handle success and halt scenarios differently. Understanding when to use each method is crucial for proper error handling and control flow in your application workflows.
+CMDx offers two execution methods with different error handling approaches. Choose based on your needs: safe result handling or exception-based control flow.
 
-## Table of Contents
+## Execution Methods
 
-- [Methods Overview](#methods-overview)
-- [Non-bang Execution](#non-bang-execution)
-- [Bang Execution](#bang-execution)
-- [Direct Instantiation](#direct-instantiation)
-- [Result Details](#result-details)
-
-## Methods Overview
-
-Tasks are single-use objects. Once executed, they are frozen and cannot be executed again.
-Create a new instance for subsequent executions.
+Both methods return results, but handle failures differently:
 
 | Method | Returns | Exceptions | Use Case |
 |--------|---------|------------|----------|
@@ -22,10 +13,7 @@ Create a new instance for subsequent executions.
 
 ## Non-bang Execution
 
-The `execute` method always returns a `CMDx::Result` object regardless of execution outcome.
-This is the preferred method for most use cases.
-
-Any unhandled exceptions will be caught and returned as a task failure.
+Always returns a `CMDx::Result`, never raises exceptions. Perfect for most use cases.
 
 ```ruby
 result = CreateAccount.execute(email: "user@example.com")
@@ -43,17 +31,16 @@ result.status           #=> "success"
 
 ## Bang Execution
 
-The bang `execute!` method raises a `CMDx::Fault` based exception when tasks fail or are skipped, and returns a `CMDx::Result` object only on success.
-
-It raises any unhandled non-fault exceptions caused during execution.
+Raises `CMDx::Fault` exceptions on failure or skip. Returns results only on success.
 
 | Exception | Raised When |
 |-----------|-------------|
 | `CMDx::FailFault` | Task execution fails |
 | `CMDx::SkipFault` | Task execution is skipped |
 
-> [!IMPORTANT]
-> `execute!` behavior depends on the `task_breakpoints` or `workflow_breakpoints` configuration. By default, it raises exceptions only on failures.
+!!! warning "Important"
+
+    Behavior depends on `task_breakpoints` or `workflow_breakpoints` config. Default: only failures raise exceptions.
 
 ```ruby
 begin
@@ -107,8 +94,3 @@ result.chain        #=> Task execution chain
 result.context      #=> Context with all task data
 result.metadata     #=> Hash with execution metadata
 ```
-
----
-
-- **Prev:** [Basics - Setup](setup.md)
-- **Next:** [Basics - Context](context.md)

data/docs/basics/setup.md

@@ -1,16 +1,10 @@
 # Basics - Setup
 
-Tasks are the core building blocks of CMDx, encapsulating business logic within structured, reusable objects. Each task represents a unit of work with automatic attribute validation, error handling, and execution tracking.
-
-## Table of Contents
-
-- [Structure](#structure)
-- [Inheritance](#inheritance)
-- [Lifecycle](#lifecycle)
+Tasks are the heart of CMDx—self-contained units of business logic with built-in validation, error handling, and execution tracking.
 
 ## Structure
 
-Tasks inherit from `CMDx::Task` and require only a `work` method:
+Tasks need only two things: inherit from `CMDx::Task` and define a `work` method:
 
 ```ruby
 class ValidateDocument < CMDx::Task
@@ -20,7 +14,7 @@ class ValidateDocument < CMDx::Task
 end
 ```
 
-An exception will be raised if a work method is not defined.
+Without a `work` method, execution raises `CMDx::UndefinedMethodError`.
 
 ```ruby
 class IncompleteTask < CMDx::Task
@@ -32,8 +26,7 @@ IncompleteTask.execute #=> raises CMDx::UndefinedMethodError
 
 ## Inheritance
 
-All configuration options are inheritable by any child classes.
-Create a base class to share common configuration across tasks:
+Share configuration across tasks using inheritance:
 
 ```ruby
 class ApplicationTask < CMDx::Task
@@ -59,10 +52,11 @@ end
 
 ## Lifecycle
 
-Tasks follow a predictable call pattern with specific states and statuses:
+Tasks follow a predictable execution pattern:
+
+!!! danger "Caution"
 
-> [!CAUTION]
-> Tasks are single-use objects. Once executed, they are frozen and cannot be executed again.
+    Tasks are single-use objects. Once executed, they're frozen and immutable.
 
 | Stage | State | Status | Description |
 |-------|-------|--------|-------------|
@@ -71,8 +65,3 @@ Tasks follow a predictable call pattern with specific states and statuses:
 | **Execution** | `executing` | `success`/`failed`/`skipped` | `work` method runs |
 | **Completion** | `executed` | `success`/`failed`/`skipped` | Result finalized |
 | **Freezing** | `executed` | `success`/`failed`/`skipped` | Task becomes immutable |
-
----
-
-- **Prev:** [Getting Started](../getting_started.md)
-- **Next:** [Basics - Execution](execution.md)

data/docs/callbacks.md

@@ -1,36 +1,27 @@
 # Callbacks
 
-Callbacks provide precise control over task execution lifecycle, running custom logic at specific transition points. Callback callables have access to the same context and result information as the `execute` method, enabling rich integration patterns.
+Run custom logic at specific points during task execution. Callbacks have full access to task context and results, making them perfect for logging, notifications, cleanup, and more.
 
-Check out the [Getting Started](https://github.com/drexed/cmdx/blob/main/docs/getting_started.md#callbacks) docs for global configuration.
+See [Global Configuration](getting_started.md#callbacks) for framework-wide callback setup.
 
-> [!IMPORTANT]
-> Callbacks execute in the order they are declared within each hook type. Multiple callbacks of the same type execute in declaration order (FIFO: first in, first out).
+!!! warning "Important"
 
-## Table of Contents
-
-- [Available Callbacks](#available-callbacks)
-- [Declarations](#declarations)
-  - [Symbol References](#symbol-references)
-  - [Proc or Lambda](#proc-or-lambda)
-  - [Class or Module](#class-or-module)
-  - [Conditional Execution](#conditional-execution)
-- [Callback Removal](#callback-removal)
+    Callbacks execute in declaration order (FIFO). Multiple callbacks of the same type run sequentially.
 
 ## Available Callbacks
 
-Callbacks execute in precise lifecycle order. Here is the complete execution sequence:
+Callbacks execute in a predictable lifecycle order:
 
 ```ruby
 1. before_validation           # Pre-validation setup
-2. before_execution            # Setup and preparation
+2. before_execution            # Prepare for execution
 
-# --- Task#work executed ---
+# --- Task#work executes ---
 
-3. on_[complete|interrupted]   # Based on execution state
-4. on_executed                 # Task finished (any outcome)
-5. on_[success|skipped|failed] # Based on execution status
-6. on_[good|bad]               # Based on outcome classification
+3. on_[complete|interrupted]   # State-based (execution lifecycle)
+4. on_executed                 # Always runs after work completes
+5. on_[success|skipped|failed] # Status-based (business outcome)
+6. on_[good|bad]               # Outcome-based (success/skip vs fail)
 ```
 
 ## Declarations
@@ -73,7 +64,7 @@ Use anonymous functions for inline callback logic:
 ```ruby
 class ProcessBooking < CMDx::Task
   # Proc
-  on_interrupted proc { |task| ReservationSystem.pause! }
+  on_interrupted proc { ReservationSystem.pause! }
 
   # Lambda
   on_complete -> { ReservationSystem.resume! }
@@ -120,10 +111,10 @@ class ProcessBooking < CMDx::Task
   before_execution :notify_guest, if: :messaging_enabled?, unless: :messaging_blocked?
 
   # Proc
-  on_failure :increment_failure, if: ->(task) { Rails.env.production? && task.class.name.include?("Legacy") }
+  on_failure :increment_failure, if: -> { Rails.env.production? && self.class.name.include?("Legacy") }
 
   # Lambda
-  on_success :ping_housekeeping, if: proc { |task| task.context.rooms_need_cleaning? }
+  on_success :ping_housekeeping, if: proc { context.rooms_need_cleaning? }
 
   # Class or Module
   on_complete :send_confirmation, unless: MessagingPermissionCheck
@@ -138,7 +129,7 @@ class ProcessBooking < CMDx::Task
   private
 
   def messaging_enabled?
-    context.guest.messaging_preference.present?
+    context.guest.messaging_preference == true
   end
 
   def messaging_blocked?
@@ -149,10 +140,11 @@ end
 
 ## Callback Removal
 
-Remove callbacks at runtime for dynamic behavior control:
+Remove unwanted callbacks dynamically:
+
+!!! warning "Important"
 
-> [!IMPORTANT]
-> Only one removal operation is allowed per `deregister` call. Multiple removals require separate calls.
+    Each `deregister` call removes one callback. Use multiple calls for batch removals.
 
 ```ruby
 class ProcessBooking < CMDx::Task
@@ -163,8 +155,3 @@ class ProcessBooking < CMDx::Task
   deregister :callback, :on_complete, BookingConfirmationCallback
 end
 ```
-
----
-
-- **Prev:** [Attributes - Defaults](attributes/defaults.md)
-- **Next:** [Middlewares](middlewares.md)

data/docs/deprecation.md

@@ -1,28 +1,16 @@
 # Task Deprecation
 
-Task deprecation provides a systematic approach to managing legacy tasks in CMDx applications. The deprecation system enables controlled migration paths by issuing warnings, logging messages, or preventing execution of deprecated tasks entirely, helping teams maintain code quality while providing clear upgrade paths.
-
-## Table of Contents
-
-- [Modes](#modes)
-  - [Raise](#raise)
-  - [Log](#log)
-  - [Warn](#warn)
-- [Declarations](#declarations)
-  - [Symbol or String](#symbol-or-string)
-  - [Boolean or Nil](#boolean-or-nil)
-  - [Method](#method)
-  - [Proc or Lambda](#proc-or-lambda)
-  - [Class or Module](#class-or-module)
+Manage legacy tasks gracefully with built-in deprecation support. Choose how to handle deprecated tasks—log warnings for awareness, issue Ruby warnings for development, or prevent execution entirely.
 
 ## Modes
 
 ### Raise
 
-`:raise` mode prevents task execution entirely. Use this for tasks that should no longer be used under any circumstances.
+Prevent task execution completely. Perfect for tasks that must no longer run.
+
+!!! warning
 
-> [!WARNING]
-> Use `:raise` mode carefully in production environments as it will break existing workflows immediately.
+    Use `:raise` mode carefully—it will break existing workflows immediately.
 
 ```ruby
 class ProcessObsoleteAPI < CMDx::Task
@@ -39,7 +27,7 @@ result = ProcessObsoleteAPI.execute
 
 ### Log
 
-`:log` mode allows continued usage while tracking deprecation warnings. Perfect for gradual migration scenarios where immediate replacement isn't feasible.
+Allow execution while tracking deprecation in logs. Ideal for gradual migrations.
 
 ```ruby
 class ProcessLegacyFormat < CMDx::Task
@@ -62,7 +50,7 @@ result.successful? #=> true
 
 ### Warn
 
-`:warn` mode issues Ruby warnings visible in development and testing environments. Useful for alerting developers without affecting production logging.
+Issue Ruby warnings visible during development and testing. Keeps production logs clean while alerting developers.
 
 ```ruby
 class ProcessOldData < CMDx::Task
@@ -77,7 +65,7 @@ result = ProcessOldData.execute
 result.successful? #=> true
 
 # Ruby warning appears in stderr:
-# [ProcessOldData] DEPRECATED: migrate to replacement or discontinue use
+# [ProcessOldData] DEPRECATED: migrate to a replacement or discontinue use
 ```
 
 ## Declarations
@@ -155,8 +143,3 @@ class OutdatedConnector < CMDx::Task
   settings(deprecated: OutdatedTaskDeprecator.new)
 end
 ```
-
----
-
-- **Prev:** [Internationalization (i18n)](internationalization.md)
-- **Next:** [Workflows](workflows.md)

data/docs/getting_started.md

@@ -1,51 +1,33 @@
 # Getting Started
 
-CMDx is a Ruby framework for building maintainable, observable business logic through composable command objects. Design robust workflows with automatic attribute validation, structured error handling, comprehensive logging, and intelligent execution flow control.
-
-**Common Challenges:**
-
-- Inconsistent patterns across implementations
-- Minimal or no logging, making debugging painful
-- Fragile designs that erode developer confidence
-
-**CMDx Solutions:**
-
-- Establishes a consistent, standardized design
-- Provides flow control and error handling
-- Supports composable, reusable workflows
-- Includes detailed logging for observability
-- Defines input attributes with fallback defaults
-- Adds validations and type coercions
-- Plus many other developer-friendly tools
-
-## Table of Contents
-
-- [Compose, Execute, React, Observe pattern](#compose-execute-react-observe-pattern)
-- [Installation](#installation)
-- [Configuration Hierarchy](#configuration-hierarchy)
-- [Global Configuration](#global-configuration)
-  - [Breakpoints](#breakpoints)
-  - [Logging](#logging)
-  - [Middlewares](#middlewares)
-  - [Callbacks](#callbacks)
-  - [Coercions](#coercions)
-  - [Validators](#validators)
-- [Task Configuration](#task-configuration)
-  - [Settings](#settings)
-  - [Registrations](#registrations)
-- [Configuration Management](#configuration-management)
-  - [Access](#access)
-  - [Resetting](#resetting)
-- [Task Generator](#task-generator)
-
-## Compose, Execute, React, Observe pattern
-
-CMDx encourages breaking business logic into composable tasks. Each task can be combined into larger workflows, executed with standardized flow control, and fully observed through logging, validations, and context.
-
-- *Compose* → Define small, contract-driven tasks with typed attributes, validations, and natural workflow composition.
-- *Execute* → Run tasks with clear outcomes, intentional halts, and pluggable behaviors via middlewares and callbacks.
-- *React* → Adapt to outcomes by chaining follow-up tasks, handling faults, or shaping future flows.
-- *Observe* → Capture immutable results, structured logs, and full execution chains for reliable tracing and insight.
+CMDx is a Ruby framework for building maintainable, observable business logic through composable command objects. It brings structure, consistency, and powerful developer tools to your business processes.
+
+**Common challenges it solves:**
+
+- Inconsistent service object patterns across your codebase
+- Limited logging makes debugging a nightmare
+- Fragile error handling erodes confidence
+
+**What you get:**
+
+- Consistent, standardized architecture
+- Built-in flow control and error handling
+- Composable, reusable workflows
+- Comprehensive logging for observability
+- Attribute validation with type coercions
+- Sensible defaults and developer-friendly APIs
+
+## The CERO Pattern
+
+CMDx embraces the Compose, Execute, React, Observe (CERO) pattern—a simple yet powerful approach to building reliable business logic.
+
+🧩 **Compose** — Define small, focused tasks with typed attributes and validations
+
+⚡ **Execute** — Run tasks with clear outcomes and pluggable behaviors
+
+🔄 **React** — Adapt to outcomes by chaining follow-up tasks or handling faults
+
+🔍 **Observe** — Capture structured logs and execution chains for debugging
 
 ## Installation
 
@@ -65,39 +47,78 @@ This creates `config/initializers/cmdx.rb` file.
 
 ## Configuration Hierarchy
 
-CMDx follows a two-tier configuration hierarchy:
+CMDx uses a straightforward two-tier configuration system:
 
-1. **Global Configuration**: Framework-wide defaults
-2. **Task Settings**: Class-level overrides via `settings`
+1. **Global Configuration** — Framework-wide defaults
+2. **Task Settings** — Class-level overrides using `settings`
 
-> [!IMPORTANT]
-> Task-level settings take precedence over global configuration. Settings are inherited from superclasses and can be overridden in subclasses.
+!!! warning "Important"
+
+    Task settings take precedence over global config. Settings are inherited from parent classes and can be overridden in subclasses.
 
 ## Global Configuration
 
-Global configuration settings apply to all tasks inherited from `CMDx::Task`.
-Globally these settings are initialized with sensible defaults.
+Configure framework-wide defaults that apply to all tasks. These settings come with sensible defaults out of the box.
 
 ### Breakpoints
 
-Raise `CMDx::Fault` when a task called with `execute!` returns a matching status.
+Control when `execute!` raises a `CMDx::Fault` based on task status.
 
 ```ruby
 CMDx.configure do |config|
-  # String or Array[String]
-  config.task_breakpoints = "failed"
+  config.task_breakpoints = "failed" # String or Array[String]
 end
 ```
 
-Workflow breakpoints stops execution and of workflow pipeline on the first task that returns a matching status and throws its `CMDx::Fault`.
+For workflows, configure which statuses halt the execution pipeline:
 
 ```ruby
 CMDx.configure do |config|
-  # String or Array[String]
   config.workflow_breakpoints = ["skipped", "failed"]
 end
 ```
 
+### Backtraces
+
+Enable detailed backtraces for non-fault exceptions to improve debugging. Optionally clean up stack traces to remove framework noise.
+
+!!! note
+
+    In Rails environments, `backtrace_cleaner` defaults to `Rails.backtrace_cleaner.clean`.
+
+```ruby
+CMDx.configure do |config|
+  # Truthy
+  config.backtrace = true
+
+  # Via callable (must respond to `call(backtrace)`)
+  config.backtrace_cleaner = AdvanceCleaner.new
+
+  # Via proc or lambda
+  config.backtrace_cleaner = ->(backtrace) { backtrace[0..5] }
+end
+```
+
+### Exception Handlers
+
+Register handlers that run when non-fault exceptions occur.
+
+!!! tip
+
+    Use exception handlers to send errors to your APM of choice.
+
+```ruby
+CMDx.configure do |config|
+  # Via callable (must respond to `call(task, exception)`)
+  config.exception_handler = NewRelicReporter
+
+  # Via proc or lambda
+  config.exception_handler = proc do |task, exception|
+    APMService.report(exception, extra_data: { task: task.name, id: task.id })
+  end
+end
+```
+
 ### Logging
 
 ```ruby
@@ -108,7 +129,7 @@ end
 
 ### Middlewares
 
-See the [Middelwares](#https://github.com/drexed/cmdx/blob/main/docs/middlewares.md#declarations) docs for task level configurations.
+See the [Middlewares](middlewares.md#declarations) docs for task level configurations.
 
 ```ruby
 CMDx.configure do |config|
@@ -132,12 +153,13 @@ CMDx.configure do |config|
 end
 ```
 
-> [!NOTE]
-> Middlewares are executed in registration order. Each middleware wraps the next, creating an execution chain around task logic.
+!!! note
+
+    Middlewares are executed in registration order. Each middleware wraps the next, creating an execution chain around task logic.
 
 ### Callbacks
 
-See the [Callbacks](#https://github.com/drexed/cmdx/blob/main/docs/callbacks.md#declarations) docs for task level configurations.
+See the [Callbacks](callbacks.md#declarations) docs for task level configurations.
 
 ```ruby
 CMDx.configure do |config|
@@ -163,7 +185,7 @@ end
 
 ### Coercions
 
-See the [Attributes - Coercions](#https://github.com/drexed/cmdx/blob/main/docs/attributes/coercions.md#declarations) docs for task level configurations.
+See the [Attributes - Coercions](attributes/coercions.md#declarations) docs for task level configurations.
 
 ```ruby
 CMDx.configure do |config|
@@ -189,7 +211,7 @@ end
 
 ### Validators
 
-See the [Attributes - Validations](#https://github.com/drexed/cmdx/blob/main/docs/attributes/validations.md#declarations) docs for task level configurations.
+See the [Attributes - Validations](attributes/validations.md#declarations) docs for task level configurations.
 
 ```ruby
 CMDx.configure do |config|
@@ -224,6 +246,8 @@ class GenerateInvoice < CMDx::Task
     # Global configuration overrides
     task_breakpoints: ["failed"],                # Breakpoint override
     workflow_breakpoints: [],                    # Breakpoint override
+    backtrace: true,                             # Toggle backtrace
+    backtrace_cleaner: ->(bt) { bt[0..5] },      # Backtrace cleaner
     logger: CustomLogger.new($stdout),           # Custom logger
 
     # Task configuration settings
@@ -231,7 +255,10 @@ class GenerateInvoice < CMDx::Task
     log_level: :info,                            # Log level override
     log_formatter: CMDx::LogFormatters::Json.new # Log formatter override
     tags: ["billing", "financial"],              # Logging tags
-    deprecated: true                             # Task deprecations
+    deprecated: true,                            # Task deprecations
+    retries: 3,                                  # Non-fault exception retries
+    retry_on: [External::ApiError],              # List of exceptions to retry on
+    retry_jitter: 1                              # Space between retry iteration, eg: current retry num + 1
   )
 
   def work
@@ -240,13 +267,13 @@ class GenerateInvoice < CMDx::Task
 end
 ```
 
-> [!TIP]
-> Use task-level settings for tasks that require special handling, such as financial reporting, external API integrations, or critical system operations.
+!!! warning "Important"
+
+    Retries reuse the same context. By default, all `StandardError` exceptions are retried unless you specify `retry_on`.
 
 ### Registrations
 
-Register middlewares, callbacks, coercions, and validators on a specific task.
-Deregister options that should not be available.
+Register or deregister middlewares, callbacks, coercions, and validators for specific tasks:
 
 ```ruby
 class SendCampaignEmail < CMDx::Task
@@ -298,8 +325,9 @@ end
 
 ### Resetting
 
-> [!WARNING]
-> Resetting configuration affects the entire application. Use primarily in test environments or during application initialization.
+!!! warning
+
+    Resetting affects your entire application. Use this primarily in test environments.
 
 ```ruby
 # Reset to framework defaults
@@ -336,10 +364,6 @@ class ModerateBlogPost < CMDx::Task
 end
 ```
 
-> [!TIP]
-> Use **present tense verbs + noun** for task names, eg: `ModerateBlogPost`, `ScheduleAppointment`, `ValidateDocument`
-
----
+!!! tip
 
-- **Prev:** [Tips and Tricks](tips_and_tricks.md)
-- **Next:** [Basics - Setup](basics/setup.md)
+    Use **present tense verbs + noun** for task names, eg: `ModerateBlogPost`, `ScheduleAppointment`, `ValidateDocument`