cmdx 1.7.5 → 1.9.0

data/docs/basics/chain.md

@@ -1,20 +1,14 @@
 # Basics - Chain
 
-Chains automatically group related task executions within a thread, providing unified tracking, correlation, and execution context management. Each thread maintains its own chain through thread-local storage, eliminating the need for manual coordination.
-
-## Table of Contents
-
-- [Management](#management)
-- [Links](#links)
-- [Inheritance](#inheritance)
-- [Structure](#structure)
+Chains automatically track related task executions within a thread. Think of them as execution traces that help you understand what happened and in what order.
 
 ## Management
 
-Each thread maintains its own chain context through thread-local storage, providing automatic isolation without manual coordination.
+Each thread maintains its own isolated chain using thread-local storage.
 
-> [!WARNING]
-> Chain operations are thread-local. Never share chain references across threads as this can lead to race conditions and data corruption.
+!!! warning
+
+    Chains are thread-local. Don't share chain references across threads—it causes race conditions.
 
 ```ruby
 # Thread A
@@ -36,10 +30,11 @@ CMDx::Chain.clear    #=> Clears current thread's chain
 
 ## Links
 
-Every task execution automatically creates or joins the current thread's chain:
+Tasks automatically create or join the current thread's chain:
+
+!!! warning "Important"
 
-> [!IMPORTANT]
-> Chain creation is automatic and transparent. You don't need to manually manage chain lifecycle.
+    Chain management is automatic—no manual lifecycle handling needed.
 
 ```ruby
 class ImportDataset < CMDx::Task
@@ -62,7 +57,7 @@ end
 
 ## Inheritance
 
-When tasks call subtasks within the same thread, all executions automatically inherit the current chain, creating a unified execution trail.
+Subtasks automatically inherit the current thread's chain, building a unified execution trail:
 
 ```ruby
 class ImportDataset < CMDx::Task
@@ -87,10 +82,11 @@ chain.results.map { |r| r.task.class }
 
 ## Structure
 
-Chains provide comprehensive execution information with state delegation:
+Chains expose comprehensive execution information:
 
-> [!IMPORTANT]
-> Chain state always reflects the first (outer-most) task result, not individual subtask outcomes. Subtasks maintain their own success/failure states.
+!!! warning "Important"
+
+    Chain state reflects the first (outermost) task result. Subtasks maintain their own states.
 
 ```ruby
 result = ImportDataset.execute(dataset_id: 456)
@@ -110,8 +106,3 @@ chain.results.each_with_index do |result, index|
   puts "#{index}: #{result.task.class} - #{result.status}"
 end
 ```
-
----
-
-- **Prev:** [Basics - Context](context.md)
-- **Next:** [Interruptions - Halt](../interruptions/halt.md)

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)