cmdx 1.0.0 → 1.1.0

data/docs/middlewares.md

@@ -4,6 +4,7 @@ Middleware provides Rack-style wrappers around task execution for cross-cutting
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Using Middleware](#using-middleware)
   - [Class Middleware](#class-middleware)
   - [Instance Middleware](#instance-middleware)
@@ -16,15 +17,24 @@ Middleware provides Rack-style wrappers around task execution for cross-cutting
   - [Correlate Middleware](#correlate-middleware)
 - [Writing Custom Middleware](#writing-custom-middleware)
 
+## TLDR
+
+- **Purpose** - Rack-style wrappers for cross-cutting concerns (auth, logging, caching)
+- **Declaration** - Use `use` method with classes, instances, or procs
+- **Execution order** - Nested fashion (first declared wraps all others)
+- **Short-circuiting** - Middleware can halt execution by not calling next callable
+- **Inheritance** - Middleware is inherited from parent classes
+- **Built-in** - Includes Timeout and Correlate middleware
+
 ## Using Middleware
 
 Declare middleware using the `use` method in your task classes:
 
 ```ruby
 class ProcessOrderTask < CMDx::Task
-  use AuthenticationMiddleware
-  use LoggingMiddleware, level: :info
-  use CachingMiddleware, ttl: 300
+  use :middleware, AuthenticationMiddleware
+  use :middleware, LoggingMiddleware, level: :info
+  use :middleware, CachingMiddleware, ttl: 300
 
   def call
     context.order = Order.find(order_id)
@@ -61,7 +71,7 @@ class AuditMiddleware < CMDx::Middleware
 end
 
 class ProcessOrderTask < CMDx::Task
-  use AuditMiddleware, action: 'process', resource_type: 'Order'
+  use :middleware, AuditMiddleware, action: 'process', resource_type: 'Order'
 
   def call
     context.order = Order.find(order_id)
@@ -76,7 +86,7 @@ Pre-configured middleware instances for complex initialization:
 
 ```ruby
 class ProcessOrderTask < CMDx::Task
-  use LoggingMiddleware.new(
+  use :middleware, LoggingMiddleware.new(
     level: :debug,
     formatter: JSON::JSONFormatter.new,
     tags: ['order', 'payment']
@@ -94,7 +104,7 @@ Inline middleware for simple cases:
 
 ```ruby
 class ProcessOrderTask < CMDx::Task
-  use proc { |task, callable|
+  use :middleware, proc { |task, callable|
     start_time = Time.now
     result = callable.call(task)
     duration = Time.now - start_time
@@ -115,9 +125,9 @@ Middleware executes in nested fashion - first declared wraps all others:
 
 ```ruby
 class ProcessOrderTask < CMDx::Task
-  use TimingMiddleware         # 1st: outermost
-  use AuthenticationMiddleware # 2nd: middle
-  use ValidationMiddleware     # 3rd: innermost
+  use :middleware, TimingMiddleware         # 1st: outermost
+  use :middleware, AuthenticationMiddleware # 2nd: middle
+  use :middleware, ValidationMiddleware     # 3rd: innermost
 
   def call
     # Core logic executes last
@@ -163,7 +173,7 @@ class RateLimitMiddleware < CMDx::Middleware
 end
 
 class SendEmailTask < CMDx::Task
-  use RateLimitMiddleware, limit: 50, window: 1.hour
+  use :middleware, RateLimitMiddleware, limit: 50, window: 1.hour
 
   def call
     # Only executes if rate limit check passes
@@ -182,14 +192,14 @@ Middleware is inherited from parent classes, enabling application-wide patterns:
 
 ```ruby
 class ApplicationTask < CMDx::Task
-  use RequestIdMiddleware      # All tasks get request tracking
-  use PerformanceMiddleware    # All tasks get performance monitoring
-  use ErrorReportingMiddleware # All tasks get error reporting
+  use :middleware, RequestIdMiddleware      # All tasks get request tracking
+  use :middleware, PerformanceMiddleware    # All tasks get performance monitoring
+  use :middleware, ErrorReportingMiddleware # All tasks get error reporting
 end
 
 class ProcessOrderTask < ApplicationTask
-  use AuthenticationMiddleware  # Specific to order processing
-  use OrderValidationMiddleware # Domain-specific validation
+  use :middleware, AuthenticationMiddleware  # Specific to order processing
+  use :middleware, OrderValidationMiddleware # Domain-specific validation
 
   def call
     # Inherits all ApplicationTask middleware plus order-specific ones
@@ -210,7 +220,7 @@ Enforces execution time limits with support for static and dynamic timeout value
 
 ```ruby
 class ProcessLargeReportTask < CMDx::Task
-  use CMDx::Middlewares::Timeout, seconds: 300 # 5 minutes
+  use :middleware, CMDx::Middlewares::Timeout, seconds: 300 # 5 minutes
 
   def call
     # Long-running report generation
@@ -219,7 +229,7 @@ end
 
 # Default timeout (3 seconds when no value specified)
 class QuickValidationTask < CMDx::Task
-  use CMDx::Middlewares::Timeout # Uses 3 seconds default
+  use :middleware, CMDx::Middlewares::Timeout # Uses 3 seconds default
 
   def call
     # Fast validation logic
@@ -234,7 +244,7 @@ The middleware supports dynamic timeout calculation using method names, procs, a
 ```ruby
 # Method-based timeout calculation
 class ProcessOrderTask < CMDx::Task
-  use CMDx::Middlewares::Timeout, seconds: :calculate_timeout
+  use :middleware, CMDx::Middlewares::Timeout, seconds: :calculate_timeout
 
   def call
     # Task execution with dynamic timeout
@@ -255,7 +265,7 @@ end
 
 # Proc-based timeout for inline calculation
 class ProcessWorkflowTask < CMDx::Task
-  use CMDx::Middlewares::Timeout, seconds: -> {
+  use :middleware, CMDx::Middlewares::Timeout, seconds: -> {
     context.workflow_size > 100 ? 120 : 60
   }
 
@@ -267,7 +277,7 @@ end
 
 # Context-aware timeout calculation
 class GenerateReportTask < CMDx::Task
-  use CMDx::Middlewares::Timeout, seconds: :report_timeout
+  use :middleware, CMDx::Middlewares::Timeout, seconds: :report_timeout
 
   def call
     context.report = ReportGenerator.create(report_params)
@@ -299,12 +309,12 @@ The middleware follows this precedence for determining timeout values:
 ```ruby
 # Static timeout - highest precedence when specified
 class ProcessOrderTask < CMDx::Task
-  use CMDx::Middlewares::Timeout, seconds: 45 # Always 45 seconds
+  use :middleware, CMDx::Middlewares::Timeout, seconds: 45 # Always 45 seconds
 end
 
 # Method-based timeout - calls task method
 class ProcessOrderTask < CMDx::Task
-  use CMDx::Middlewares::Timeout, seconds: :dynamic_timeout
+  use :middleware, CMDx::Middlewares::Timeout, seconds: :dynamic_timeout
 
   private
   def dynamic_timeout
@@ -314,7 +324,7 @@ end
 
 # Default fallback when method returns nil
 class ProcessOrderTask < CMDx::Task
-  use CMDx::Middlewares::Timeout, seconds: :might_return_nil
+  use :middleware, CMDx::Middlewares::Timeout, seconds: :might_return_nil
 
   private
   def might_return_nil
@@ -330,7 +340,7 @@ Apply timeout middleware conditionally based on environment or task state:
 ```ruby
 # Environment-based conditional timeout
 class ProcessOrderTask < CMDx::Task
-  use CMDx::Middlewares::Timeout,
+  use :middleware, CMDx::Middlewares::Timeout,
       seconds: 60,
       unless: -> { Rails.env.development? }
 
@@ -343,7 +353,7 @@ end
 
 # Context-based conditional timeout
 class SendEmailTask < CMDx::Task
-  use CMDx::Middlewares::Timeout,
+  use :middleware, CMDx::Middlewares::Timeout,
       seconds: 30,
       if: :timeout_enabled?
 
@@ -360,7 +370,7 @@ end
 
 # Combined dynamic timeout with conditions
 class ProcessComplexOrderTask < CMDx::Task
-  use CMDx::Middlewares::Timeout,
+  use :middleware, CMDx::Middlewares::Timeout,
       seconds: :calculate_timeout,
       unless: :skip_timeout?
 
@@ -389,11 +399,11 @@ Apply timeout middleware globally with inheritance:
 
 ```ruby
 class ApplicationTask < CMDx::Task
-  use CMDx::Middlewares::Timeout, seconds: 60 # Default 60 seconds for all tasks
+  use :middleware, CMDx::Middlewares::Timeout, seconds: 60 # Default 60 seconds for all tasks
 end
 
 class QuickTask < ApplicationTask
-  use CMDx::Middlewares::Timeout, seconds: 15 # Override with 15 seconds
+  use :middleware, CMDx::Middlewares::Timeout, seconds: 15 # Override with 15 seconds
 
   def call
     # Fast operation with shorter timeout
@@ -401,7 +411,7 @@ class QuickTask < ApplicationTask
 end
 
 class LongRunningTask < ApplicationTask
-  use CMDx::Middlewares::Timeout, seconds: :dynamic_timeout
+  use :middleware, CMDx::Middlewares::Timeout, seconds: :dynamic_timeout
 
   def call
     # Long operation with dynamic timeout
@@ -427,7 +437,7 @@ Manages correlation IDs for request tracing across task boundaries. This middlew
 
 ```ruby
 class ProcessApiRequestTask < CMDx::Task
-  use CMDx::Middlewares::Correlate
+  use :middleware, CMDx::Middlewares::Correlate
 
   def call
     # Correlation ID is automatically managed
@@ -446,19 +456,19 @@ The middleware follows a hierarchical precedence system for determining correlat
 
 # 1a. Static string ID
 class ProcessOrderTask < CMDx::Task
-  use CMDx::Middlewares::Correlate, id: "fixed-correlation-123"
+  use :middleware, CMDx::Middlewares::Correlate, id: "fixed-correlation-123"
 end
 ProcessOrderTask.call # Always uses "fixed-correlation-123"
 
 # 1b. Dynamic proc/lambda ID
 class ProcessOrderTask < CMDx::Task
-  use CMDx::Middlewares::Correlate, id: -> { "order-#{order_id}-#{rand(1000)}" }
+  use :middleware, CMDx::Middlewares::Correlate, id: -> { "order-#{order_id}-#{rand(1000)}" }
 end
 ProcessOrderTask.call(order_id: 456) # Uses "order-456-847" (random number varies)
 
 # 1c. Method-based ID
 class ProcessOrderTask < CMDx::Task
-  use CMDx::Middlewares::Correlate, id: :correlation_method
+  use :middleware, CMDx::Middlewares::Correlate, id: :correlation_method
 
   private
 
@@ -488,7 +498,7 @@ Set fixed or dynamic correlation IDs for specific tasks or workflows using strin
 ```ruby
 # Static string correlation ID
 class ProcessPaymentTask < CMDx::Task
-  use CMDx::Middlewares::Correlate, id: "payment-processing"
+  use :middleware, CMDx::Middlewares::Correlate, id: "payment-processing"
 
   def call
     # Always uses "payment-processing" as correlation ID
@@ -499,7 +509,7 @@ end
 
 # Dynamic correlation ID using proc/lambda
 class ProcessOrderTask < CMDx::Task
-  use CMDx::Middlewares::Correlate, id: -> { "order-#{order_id}-#{Time.now.to_i}" }
+  use :middleware, CMDx::Middlewares::Correlate, id: -> { "order-#{order_id}-#{Time.now.to_i}" }
 
   def call
     # Dynamic correlation ID based on order and timestamp
@@ -511,7 +521,7 @@ end
 
 # Method-based correlation ID
 class ProcessApiRequestTask < CMDx::Task
-  use CMDx::Middlewares::Correlate, id: :generate_correlation_id
+  use :middleware, CMDx::Middlewares::Correlate, id: :generate_correlation_id
 
   def call
     # Uses correlation ID from generate_correlation_id method
@@ -527,7 +537,7 @@ end
 
 # Symbol fallback when method doesn't exist
 class ProcessWorkflowTask < CMDx::Task
-  use CMDx::Middlewares::Correlate, id: :workflow_processing
+  use :middleware, CMDx::Middlewares::Correlate, id: :workflow_processing
 
   def call
     # Uses :workflow_processing as correlation ID (symbol as-is)
@@ -544,7 +554,7 @@ Apply correlation middleware conditionally based on environment or task state:
 ```ruby
 class ProcessOrderTask < CMDx::Task
   # Only apply correlation in production environments
-  use CMDx::Middlewares::Correlate, unless: -> { Rails.env.development? }
+  use :middleware, CMDx::Middlewares::Correlate, unless: -> { Rails.env.development? }
 
   def call
     context.order = Order.find(order_id)
@@ -554,7 +564,7 @@ end
 
 class SendEmailTask < CMDx::Task
   # Apply correlation only when tracing is enabled
-  use CMDx::Middlewares::Correlate, if: :tracing_enabled?
+  use :middleware, CMDx::Middlewares::Correlate, if: :tracing_enabled?
 
   def call
     EmailService.deliver(email_params)
@@ -574,7 +584,7 @@ Use correlation blocks to establish correlation contexts for groups of related t
 
 ```ruby
 class ProcessOrderWorkflowTask < CMDx::Task
-  use CMDx::Middlewares::Correlate
+  use :middleware, CMDx::Middlewares::Correlate
 
   def call
     # Establish correlation context for entire workflow
@@ -594,7 +604,7 @@ Apply correlation middleware globally to all tasks:
 
 ```ruby
 class ApplicationTask < CMDx::Task
-  use CMDx::Middlewares::Correlate # All tasks get correlation management
+  use :middleware, CMDx::Middlewares::Correlate # All tasks get correlation management
 end
 
 class ProcessOrderTask < ApplicationTask
@@ -638,7 +648,7 @@ class ApiController < ApplicationController
 end
 
 class ProcessOrderTask < CMDx::Task
-  use CMDx::Middlewares::Correlate
+  use :middleware, CMDx::Middlewares::Correlate
 
   def call
     # Inherits correlation ID from controller thread context
@@ -651,7 +661,7 @@ end
 
 # Alternative: Task-specific correlation for API endpoints
 class ProcessApiOrderTask < CMDx::Task
-  use CMDx::Middlewares::Correlate, id: -> { "api-order-#{context.request_id}" }
+  use :middleware, CMDx::Middlewares::Correlate, id: -> { "api-order-#{context.request_id}" }
 
   def call
     # Uses correlation ID specific to this API request

data/docs/outcomes/result.md

@@ -7,6 +7,7 @@ inspecting task execution outcomes and chaining task operations.
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Core Result Attributes](#core-result-attributes)
 - [State and Status Information](#state-and-status-information)
 - [Execution Outcome Analysis](#execution-outcome-analysis)
@@ -17,6 +18,14 @@ inspecting task execution outcomes and chaining task operations.
 - [Pattern Matching](#pattern-matching)
 - [Serialization and Inspection](#serialization-and-inspection)
 
+## TLDR
+
+- **Result object** - Comprehensive return value from task execution with `task`, `context`, `chain`, `metadata`
+- **Status checking** - Use `result.success?`, `result.failed?`, `result.skipped?` for outcomes
+- **State checking** - Use `result.complete?`, `result.interrupted?`, `result.executed?` for lifecycle
+- **Callbacks** - Chain with `.on_success`, `.on_failed`, `.on_good`, `.on_bad` for conditional logic
+- **Failure analysis** - Use `result.caused_failure`, `result.threw_failure` to trace failure chains
+
 ## Core Result Attributes
 
 Every result provides access to essential execution information:

data/docs/outcomes/states.md

@@ -7,6 +7,7 @@ decision making and monitoring.
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [State Definitions](#state-definitions)
 - [State Transitions](#state-transitions)
 - [State Predicates](#state-predicates)
@@ -15,6 +16,14 @@ decision making and monitoring.
 - [State Inspection and Monitoring](#state-inspection-and-monitoring)
 - [State Persistence and Logging](#state-persistence-and-logging)
 
+## TLDR
+
+- **States** - Track execution lifecycle: `initialized` → `executing` → `complete`/`interrupted`
+- **Automatic** - States are managed automatically by the framework, never modify manually
+- **Predicates** - Check with `result.complete?`, `result.interrupted?`, `result.executed?`
+- **Callbacks** - Use `.on_complete`, `.on_interrupted`, `.on_executed` for lifecycle events
+- **vs Status** - State = where in lifecycle, Status = how execution ended
+
 ## State Definitions
 
 | State         | Description |

data/docs/outcomes/statuses.md

@@ -4,6 +4,7 @@ Statuses represent the outcome of task execution logic, indicating how the task'
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Status Definitions](#status-definitions)
 - [Status Characteristics](#status-characteristics)
 - [Status Predicates](#status-predicates)
@@ -14,6 +15,14 @@ Statuses represent the outcome of task execution logic, indicating how the task'
 - [Status Serialization and Inspection](#status-serialization-and-inspection)
 - [Status vs State vs Outcome](#status-vs-state-vs-outcome)
 
+## TLDR
+
+- **Statuses** - Business outcome of execution: `success` (default), `skipped` (via `skip!`), `failed` (via `fail!`)
+- **One-way transitions** - Only `success` → `skipped`/`failed`, never reverse
+- **Predicates** - Check with `result.success?`, `result.skipped?`, `result.failed?`
+- **Outcomes** - `result.good?` = success OR skipped, `result.bad?` = skipped OR failed
+- **Rich metadata** - Both `skip!()` and `fail!()` accept metadata for context
+
 ## Status Definitions
 
 | Status    | Description |

data/docs/parameters/coercions.md

@@ -7,6 +7,7 @@ string-to-integer conversion to complex JSON parsing and custom type handling.
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Coercion Fundamentals](#coercion-fundamentals)
   - [Available Coercion Types](#available-coercion-types)
   - [Basic Type Coercion](#basic-type-coercion)
@@ -19,11 +20,19 @@ string-to-integer conversion to complex JSON parsing and custom type handling.
   - [Numeric Coercion](#numeric-coercion)
 - [Coercion with Nested Parameters](#coercion-with-nested-parameters)
 - [Coercion Error Handling](#coercion-error-handling)
-  - [Single Type Coercion Errors](#single-type-coercion-errors)
-  - [Multiple Type Coercion Errors](#multiple-type-coercion-errors)
 - [Custom Coercion Options](#custom-coercion-options)
   - [Date/Time Format Options](#datetime-format-options)
   - [BigDecimal Precision Options](#bigdecimal-precision-options)
+- [Custom Coercions](#custom-coercions)
+
+## TLDR
+
+- **Type coercion** - Automatic conversion using `type:` option (`:integer`, `:boolean`, `:array`, `:hash`, etc.)
+- **Multiple types** - Fallback with `type: [:float, :integer]` - tries each until one succeeds
+- **No conversion** - Default `:virtual` type returns values unchanged
+- **Before validation** - Coercion happens automatically before parameter validation
+- **Rich types** - Supports all Ruby built-ins plus JSON parsing for arrays/hashes
+- **Custom coercions** - Register custom coercion types
 
 ## Coercion Fundamentals
 
@@ -307,13 +316,11 @@ end
 > [!WARNING]
 > When coercion fails, CMDx provides detailed error information including the parameter name, attempted types, and specific failure reasons.
 
-### Single Type Coercion Errors
-
 ```ruby
 class ValidateUserProfileTask < CMDx::Task
 
   required :age, type: :integer
-  required :salary, type: :float
+  required :salary, type: [:float, :big_decimal]
   required :is_employed, type: :boolean
 
   def call
@@ -332,46 +339,15 @@ result = ValidateUserProfileTask.call(
 result.failed?  #=> true
 result.metadata
 #=> {
-#     reason: "age could not coerce into an integer. salary could not coerce into a float. is_employed could not coerce into a boolean.",
+#     reason: "age could not coerce into an integer. could not coerce into one of: float, big_decimal. is_employed could not coerce into a boolean.",
 #     messages: {
 #       age: ["could not coerce into an integer"],
-#       salary: ["could not coerce into a float"],
+#       salary: ["could not coerce into one of: float, big_decimal"],
 #       is_employed: ["could not coerce into a boolean"]
 #     }
 #   }
 ```
 
-### Multiple Type Coercion Errors
-
-```ruby
-class ProcessFlexibleDataTask < CMDx::Task
-
-  required :order_value, type: [:float, :integer]
-  required :customer_data, type: [:hash, :array, :string]
-
-  def call
-    # Task logic here
-  end
-
-end
-
-# Failed coercion with multiple types
-result = ProcessFlexibleDataTask.call(
-  order_value: "invalid-number",
-  customer_data: Object.new
-)
-
-result.failed?  #=> true
-result.metadata
-#=> {
-#     reason: "order_value could not coerce into one of: float, integer. customer_data could not coerce into one of: hash, array, string.",
-#     messages: {
-#       order_value: ["could not coerce into one of: float, integer"],
-#       customer_data: ["could not coerce into one of: hash, array, string"]
-#     }
-#   }
-```
-
 ## Custom Coercion Options
 
 ### Date/Time Format Options
@@ -419,6 +395,50 @@ class CalculatePricingTask < CMDx::Task
 end
 ```
 
+## Custom Coercions
+
+> [!NOTE]
+> CMDx allows you to register custom coercions for domain-specific types that aren't covered by the built-in coercions. Custom coercions can be registered globally or per-task basis.
+
+```ruby
+module MoneyCoercion
+  module_function
+
+  def call(value, options = {})
+    return value if value.is_a?(BigDecimal)
+
+    # Handle string amounts like "$123.45"
+    if value.is_a?(String)
+      clean_value = value.gsub(/[$,]/, '')
+      BigDecimal(clean_value)
+    else
+      BigDecimal(value.to_s)
+    end
+  end
+end
+
+CMDx.configure do |config|
+  config.coercions.register(:money, MoneyCoercion)
+  config.coercions.register(:slug, proc do |value|
+    value.to_s.downcase.gsub(/[^a-z0-9]+/, '-').gsub(/-+/, '-').strip('-')
+  end)
+end
+
+# Now use in any task
+class ProcessProductTask < CMDx::Task
+  required :cost, type: :money
+  required :slug, type: :slug
+
+  def call
+    cost #=> 123.45
+    slug #=> "my-blog-post-title" (URL-friendly)
+  end
+end
+```
+
+> [!TIP]
+> Custom coercions should be idempotent - calling them multiple times with the same input should produce the same result. This ensures predictable behavior when coercions are applied during parameter processing.
+
 ---
 
 - **Prev:** [Parameters - Namespacing](namespacing.md)

data/docs/parameters/defaults.md

@@ -7,6 +7,7 @@ Defaults work seamlessly with coercion, validation, and nested parameters.
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Default Value Fundamentals](#default-value-fundamentals)
   - [Fixed Value Defaults](#fixed-value-defaults)
   - [Callable Defaults](#callable-defaults)
@@ -14,6 +15,14 @@ Defaults work seamlessly with coercion, validation, and nested parameters.
 - [Defaults with Validation](#defaults-with-validation)
 - [Nested Parameter Defaults](#nested-parameter-defaults)
 
+## TLDR
+
+- **Defaults** - Provide fallback values when parameters not provided or are `nil`
+- **Fixed values** - `default: "normal"`, `default: true`, `default: []`
+- **Dynamic values** - `default: -> { Time.now }`, `default: :method_name` for callable defaults
+- **With coercion** - Defaults are subject to same type coercion as provided values
+- **With validation** - Defaults must pass same validation rules as provided values
+
 ## Default Value Fundamentals
 
 > [!NOTE]
@@ -171,7 +180,7 @@ class ValidateOrderPriorityTask < CMDx::Task
 
   # Custom validation with default
   optional :approval_code, type: :string, default: :generate_approval_code,
-    custom: { validator: ApprovalCodeValidator }
+    presence: true
 
   def call
     priority           #=> "standard" (validated against inclusion list)

data/docs/parameters/definitions.md

@@ -4,12 +4,21 @@ Parameters provide a contract to verify that task execution arguments match expe
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Parameter Fundamentals](#parameter-fundamentals)
 - [Parameter Sources](#parameter-sources)
 - [Nested Parameters](#nested-parameters)
 - [Parameter Method Generation](#parameter-method-generation)
 - [Error Handling](#error-handling)
 
+## TLDR
+
+- **Required/Optional** - Define with `required :param` and `optional :param` class methods
+- **Method generation** - Parameters become instance methods for easy access
+- **Sources** - Default `:context` source, or custom with `source: :user`
+- **Nested params** - Complex structures with `required :address do ... end`
+- **Call interface** - Parameters passed as keyword arguments to `TaskClass.call(param: value)`
+
 ## Parameter Fundamentals
 
 Parameters are defined using `required` and `optional` class methods that automatically create accessor methods within task instances. Parameters are matched from call arguments and made available as instance methods.

data/docs/parameters/namespacing.md

@@ -7,6 +7,7 @@ same name, namespacing ensures clean method resolution within tasks.
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Namespacing Fundamentals](#namespacing-fundamentals)
 - [Fixed Value Namespacing](#fixed-value-namespacing)
 - [Dynamic Source-Based Namespacing](#dynamic-source-based-namespacing)
@@ -14,6 +15,14 @@ same name, namespacing ensures clean method resolution within tasks.
 - [Advanced Namespacing Patterns](#advanced-namespacing-patterns)
 - [Error Handling with Namespacing](#error-handling-with-namespacing)
 
+## TLDR
+
+- **Method naming** - Use `prefix:` and `suffix:` to customize parameter method names
+- **Fixed prefixes** - `prefix: "user_"` creates `user_name` method for `name` parameter
+- **Dynamic prefixes** - `prefix: true` uses source name (e.g., `context_name`)
+- **Conflict resolution** - Avoid conflicts with Ruby methods or multiple same-named parameters
+- **Call arguments** - Always use original parameter names, namespacing only affects method names
+
 ## Namespacing Fundamentals
 
 > [!IMPORTANT]