cmdx 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15c3343ebbc1be1654e955561dacc79a9a27f398005bb6aa890e2167de87855a
-  data.tar.gz: 3c3e4f9d6e8d86f89e0bea6cf5573734345ea10608a7ea499f3c5ea00426d8a2
+  metadata.gz: c2d77bd913e65961bafa2851e2148df1daed63bd7047f512f53f10b9ec07b700
+  data.tar.gz: 7d86f82f6334bb4538fdbbaeafa60185de6cd55535e192832ccb8c40164996dd
 SHA512:
-  metadata.gz: a9fbc22f9d725f8798fd4efbecab466ca5baaad04ba3a4ece97a1ed878d40813b315cfaab1d2173fd220241904c061aa7b3604e34d7fa2aaa719b48df7d723b9
-  data.tar.gz: 7b2b7532835041a91867d2f0fc7f83c092f247de39d4668b33301008d847af43d352e0c8bf0820911290176af48cf396f351e651a04b126e0aebec42f415a2e9
+  metadata.gz: 4802141926139cf972a9869884fe59cddfca218a6ac8a54791e4a575ecef9f9b59039a71147097e5758e6171ef600c2d005110fc84bc27e5dd26f4930541b32d
+  data.tar.gz: b9eb23fd437ffc81ea9441273bf5602220167368af96d2190e9f2623d33eee7cf48af8c9fbfa947f802db0d378eb93f9661de04d8477759f312bf7bb0c9c1054

data/.rubocop.yml

@@ -14,6 +14,9 @@ Layout/EmptyLinesAroundClassBody:
   EnforcedStyle: empty_lines_except_namespace
 Layout/EmptyLinesAroundModuleBody:
   EnforcedStyle: empty_lines_except_namespace
+Layout/ExtraSpacing:
+  Exclude:
+    - 'lib/generators/cmdx/templates/install.rb'
 Layout/LineLength:
   Enabled: false
 Lint/MissingSuper:

data/CHANGELOG.md

@@ -1,79 +1,116 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [TODO]
+
+- Add table and pretty_table log formatters
+- Add method and proc style validations
+- Refactor parameter modules and classes for more robust usages
+
 ## [Unreleased]
 
+## [1.0.1] - 2025-07-07
+
+### Added
+- Added comprehensive internationalization support with 24 language locales
+  - Arabic, Chinese, Czech, Danish, Dutch, English, Finnish, French, German, Greek
+  - Hebrew, Hindi, Italian, Japanese, Korean, Norwegian, Polish, Portuguese
+  - Russian, Spanish, Swedish, Thai, Turkish, Vietnamese
+- Added TLDR sections to documentation for improved accessibility
+
+### Changed
+- Improved configuration template with better defaults and examples
+
 ## [1.0.0] - 2025-07-03
 
 ### Added
-- Zeitwerk gem loader
-- Add middleware support for tasks
-- Add Cursor and Copilot rules
-- Add YARDoc documentation
-- Add `perform!` and `perform` alias to class `call!` and `call`
-- Allow direct instantiation of Task and Batch objects
-- Add pattern matching of results
-- Add a `Hook` class
-- Add hooks via configuration
+- Added `Hook` class for flexible callback management
+- Added `perform!` and `perform` method aliases for class-level `call!` and `call` methods
+- Added comprehensive YARDoc documentation throughout codebase
+- Added configuration-based hook registration system
+- Added Cursor and GitHub Copilot configuration files for enhanced IDE support
+- Added middleware support for tasks enabling extensible request/response processing
+- Added pattern matching support for result objects
+- Added support for direct instantiation of Task and Workflow objects
+- Added Zeitwerk-based gem loading for improved performance and reliability
+
 ### Changed
-- Changed configuration to be a PORO class
-- Changed ArgumentError to TypeError where checking `is_a?`
-- Improve documentation readability, consistency, completeness
-- Improve test readability, consistency, completeness
-- Renames `Parameters` to `ParameterRegistry`
-- Convert hooks hash to a registry
-- Rename `Run` and its associated items to `Chain`
-- Convert `Chain` to use threads instead of passing context
-- Immutator now uses a `SKIP_CMDX_FREEZING` env var instead of `RACK_ENV` or `RAILS_ENV`
-- Rename `Hook` to `Callback`
-- Rename `Batch` to `Workflow`
+- Changed `ArgumentError` to `TypeError` for type validation consistency
+- Changed configuration from hash-based to PORO (Plain Old Ruby Object) class structure
+- Improved documentation readability, consistency, and completeness
+- Improved test suite readability, consistency, and coverage
+- Renamed `Batch` to `Workflow` to better reflect functionality
+- Renamed `Hook` to `Callback` for naming consistency
+- Renamed `Parameters` to `ParameterRegistry` for clarity
+- Renamed `Run` and associated components to `Chain` for better semantic meaning
+- Updated `Chain` to use thread-based execution instead of context passing
+- Updated `Immutator` to use `SKIP_CMDX_FREEZING` environment variable instead of `RACK_ENV`/`RAILS_ENV`
+- Updated hooks from a hash structure to registry pattern
+
 ### Removed
-- Removed configuration `task_timeout` and `batch_timeout`
+- Removed deprecated `task_timeout` and `batch_timeout` configuration settings
 
 ## [0.5.0] - 2025-03-21
 
 ### Added
-- Add `to_a` alias on array of hashes serializers
-- Add `state`, `status`, `outcome`, and `runtime` to run serializer
-- Add `on_[state]` and `on_[status]` based result callback handlers
-- Add `on_executed` state task hook
-- Add `on_good` and `on_bad` status task hook
+- Added `on_[state]` and `on_[status]` based result callback handlers
+- Added `on_executed` state hook for task completion tracking
+- Added `on_good` and `on_bad` status hooks for success/failure handling
+- Added `state`, `status`, `outcome`, and `runtime` fields to run serializer
+- Added `to_a` alias for array of hashes serializers
+
 ### Changed
-- Changed status and state hook order
+- Reordered status and state hook execution for more predictable behavior
 
 ## [0.4.0] - 2025-03-17
 
 ### Added
-- Add ANSI util
-- Add string to json parsing in hash coercion
-- Add string to json parsing in array coercion
+- Added ANSI color utility for enhanced terminal output
+- Added JSON string parsing support in array coercion
+- Added JSON string parsing support in hash coercion
+
 ### Changed
-- Skip assigning log settings if logger is nil
-- Improve ANSI escape sequence
-- Improve run inspector output
+- Improved ANSI escape sequence handling
+- Improved run inspector output formatting
+
+### Fixed
+- Fixed log settings assignment when logger is nil to prevent errors
 
 ## [0.3.0] - 2025-03-14
 
 ### Added
-- Add `progname` to logger instances
-- Add `LoggerSerializer` to standardize log output
+- Added `LoggerSerializer` for standardized log output formatting
+- Added `progname` support for logger instances
+
 ### Changed
-- Revert default log formatter to `Line`
-- Removed `pid` from result serializer
-- Fix serialization of frozen run
-- Fix `call!` not marking state of failure as interrupted
+- Removed `pid` (process ID) from result serializer output
+- Reverted default log formatter from `PrettyLine` back to `Line`
+
+### Fixed
+- Fixed `call!` method not properly marking failure state as interrupted
+- Fixed serialization issues with frozen run objects
 
 ## [0.2.0] - 2025-03-12
 
 ### Added
-- Add `PrettyJson` log formatter
-- Add `PrettyKeyValue` log formatter
-- Add `PrettyLine` log formatter
+- Added `PrettyJson` log formatter for structured JSON output
+- Added `PrettyKeyValue` log formatter for key-value pair output
+- Added `PrettyLine` log formatter for enhanced line-based output
+
 ### Changed
-- Make `PrettyLine` the default log formatter
-- Rename `MethodName` util to `NameAffix`
-- Rename `DatetimeFormatter` util to `LogTimestamp`
-- Rename `Runtime` util to `MonotonicRuntime`
-- Fix logging non hash values from raising an error
-- Fix bubbling of faults with nested halted calls
-- Wrap result logger in a `Logger#with_logger` block
+- Renamed `DatetimeFormatter` utility to `LogTimestamp` for better clarity
+- Renamed `MethodName` utility to `NameAffix` for better clarity
+- Renamed `Runtime` utility to `MonotonicRuntime` for better clarity
+- Updated `PrettyLine` to be the default log formatter
+- Updated result logger to be wrapped in `Logger#with_logger` block for better context
+
+### Fixed
+- Fixed error when logging non-hash values
+- Fixed fault bubbling behavior with nested halted calls
 
 ## [0.1.0] - 2025-03-07
 

data/README.md

@@ -100,6 +100,7 @@ end
 - [Middlewares](docs/middlewares.md)
 - [Workflows](docs/workflows.md)
 - [Logging](docs/logging.md)
+- [Internationalization (i18n)](docs/internationalization.md)
 - [Testing](docs/testing.md)
 - [AI Prompts](docs/ai_prompts.md)
 - [Tips & Tricks](docs/tips_and_tricks.md)

data/docs/ai_prompts.md

@@ -4,12 +4,22 @@ This guide provides AI prompt templates for building CMDx Task and Workflow obje
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Framework Context Template](#framework-context-template)
 - [Task Generation Templates](#task-generation-templates)
 - [Workflow Generation Templates](#workflow-generation-templates)
 - [Testing Templates](#testing-templates)
 - [Best Practices for AI Prompts](#best-practices-for-ai-prompts)
 
+## TLDR
+
+- **Purpose** - Pre-written prompts to help AI assistants generate production-ready CMDx code
+- **Templates** - Framework context, task generation, workflow generation, and testing templates
+- **Framework context** - Essential CMDx concepts and coding standards for AI understanding
+- **Task templates** - Structured prompts for generating tasks with parameters, validations, and tests
+- **Workflow templates** - Prompts for orchestrating multi-step business processes
+- **Testing templates** - Comprehensive RSpec test generation with CMDx matchers
+
 ## Framework Context Template
 
 Use this context in your AI conversations to ensure proper CMDx code generation:

data/docs/basics/call.md

@@ -4,6 +4,7 @@ Calling a task executes the business logic within it. Tasks provide two executio
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Execution Methods Overview](#execution-methods-overview)
 - [Non-bang Call (`call`)](#non-bang-call-call)
 - [Bang Call (`call!`)](#bang-call-call)
@@ -14,6 +15,14 @@ Calling a task executes the business logic within it. Tasks provide two executio
 - [Task State Lifecycle](#task-state-lifecycle)
 - [Return Value Details](#return-value-details)
 
+## TLDR
+
+- **`call`** - Always returns `CMDx::Result`, never raises exceptions (preferred)
+- **`call!`** - Returns `CMDx::Result` on success, raises `CMDx::Fault` on failure/skip
+- **Results** - Check status with `result.success?`, `result.failed?`, `result.skipped?`
+- **Callbacks** - Chain results with `.on_success`, `.on_failed`, `.on_skipped`
+- **Propagation** - Use `throw!(other_result)` to bubble up failures from subtasks
+
 ## Execution Methods Overview
 
 | Method | Returns | Exceptions | Use Case |

data/docs/basics/chain.md

@@ -4,6 +4,7 @@ A chain represents a collection of related task executions that share a common e
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Thread-Local Chain Management](#thread-local-chain-management)
 - [Automatic Chain Creation](#automatic-chain-creation)
 - [Chain Inheritance](#chain-inheritance)
@@ -12,6 +13,14 @@ A chain represents a collection of related task executions that share a common e
 - [State Delegation](#state-delegation)
 - [Serialization and Logging](#serialization-and-logging)
 
+## TLDR
+
+- **Chains** - Automatically group related task executions within the same thread
+- **Thread-local** - Each thread gets its own chain, no manual coordination needed
+- **Inheritance** - Subtasks automatically join the current thread's chain
+- **Correlation** - Chain IDs serve as correlation identifiers for tracing
+- **Access** - Use `result.chain.id` and `result.chain.results` to inspect execution trails
+
 ## Thread-Local Chain Management
 
 Chains use thread-local storage to automatically group related task executions within the same thread while maintaining isolation across different threads:

data/docs/basics/context.md

@@ -6,6 +6,7 @@ validation, and seamless data flow between related tasks.
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Loading Parameters](#loading-parameters)
 - [Accessing Data](#accessing-data)
 - [Modifying Context](#modifying-context)
@@ -14,6 +15,14 @@ validation, and seamless data flow between related tasks.
 - [Result Object Context Passing](#result-object-context-passing)
 - [Context Inspection](#context-inspection)
 
+## TLDR
+
+- **Dynamic attributes** - Access data with `context.user_id` or `context[:user_id]`
+- **Automatic loading** - Parameters become context attributes automatically
+- **Modification** - Assign data with `context.user = User.find(id)`
+- **Sharing** - Pass context between tasks with `SomeTask.call(context)`
+- **Nil safety** - Missing attributes return `nil` instead of raising errors
+
 ## Loading Parameters
 
 Context is automatically populated when calling tasks with parameters. All

data/docs/basics/setup.md

@@ -7,12 +7,21 @@ only a `call` method is required to create a functional task.
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Basic Task Structure](#basic-task-structure)
 - [Task Execution](#task-execution)
 - [Inheritance and Application Tasks](#inheritance-and-application-tasks)
 - [Generator](#generator)
 - [Task Lifecycle](#task-lifecycle)
 
+## TLDR
+
+- **Tasks** - Ruby classes that inherit from `CMDx::Task` with a `call` method
+- **Structure** - Only `call` method required, everything else is optional
+- **Execution** - Run with `MyTask.call(params)` to get a `CMDx::Result`
+- **Generator** - Use `rails g cmdx:task MyTask` to create task templates
+- **Single-use** - Tasks are frozen after execution, create new instances for each run
+
 ## Basic Task Structure
 
 ```ruby

data/docs/callbacks.md

@@ -6,6 +6,7 @@ as the `call` method, enabling rich integration patterns.
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Overview](#overview)
 - [Callback Declaration](#callback-declaration)
 - [Callback Classes](#callback-classes)
@@ -19,10 +20,19 @@ as the `call` method, enabling rich integration patterns.
 - [Conditional Execution](#conditional-execution)
 - [Callback Inheritance](#callback-inheritance)
 
+## TLDR
+
+- **Purpose** - Execute custom logic at specific points in task lifecycle
+- **Declaration** - Use method names, procs, class instances, or blocks
+- **Callback types** - Validation, execution, state, status, and outcome callbacks
+- **Execution order** - Runs in precise lifecycle order (before_execution → validation → call → status → after_execution)
+- **Conditional** - Support `:if` and `:unless` options for conditional execution
+- **Inheritance** - Callbacks are inherited, perfect for global patterns
+
 > [!TIP]
 > Callbacks are inheritable, making them perfect for setting up global logic execution patterns like tracking markers, account plan checks, or logging standards.
 
-## Callback Declaration
+## Overview
 
 Callbacks can be declared in multiple ways: method names, procs/lambdas, Callback class instances, or blocks.
 

data/docs/configuration.md

@@ -4,6 +4,7 @@ CMDx provides a flexible configuration system that allows customization at both
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Configuration Hierarchy](#configuration-hierarchy)
 - [Global Configuration](#global-configuration)
   - [Configuration Options](#configuration-options)
@@ -16,6 +17,15 @@ CMDx provides a flexible configuration system that allows customization at both
   - [Accessing Configuration](#accessing-configuration)
   - [Resetting Configuration](#resetting-configuration)
 
+## TLDR
+
+- **Hierarchy** - Global → Task Settings → Runtime (each level overrides previous)
+- **Global config** - Framework-wide defaults via `CMDx.configure`
+- **Task settings** - Class-level overrides using `task_settings!`
+- **Key options** - `task_halt`, `workflow_halt`, `logger`, `middlewares`, `callbacks`
+- **Generator** - Use `rails g cmdx:install` to create configuration file
+- **Inheritance** - Settings are inherited from parent classes
+
 ## Configuration Hierarchy
 
 CMDx follows a three-tier configuration hierarchy:
@@ -35,22 +45,7 @@ Generate a configuration file using the Rails generator:
 rails g cmdx:install
 ```
 
-This creates `config/initializers/cmdx.rb` with default settings:
-
-```ruby
-CMDx.configure do |config|
-  # Halt execution and raise fault on these result statuses when using `call!`
-  config.task_halt = CMDx::Result::FAILED
-
-  # Stop workflow execution when tasks return these statuses
-  # Note: Skipped tasks continue processing by default
-  config.workflow_halt = CMDx::Result::FAILED
-
-  # Logger with formatter - see available formatters at:
-  # https://github.com/drexed/cmdx/tree/main/lib/cmdx/log_formatters
-  config.logger = Logger.new($stdout, formatter: CMDx::LogFormatters::Line.new)
-end
-```
+This creates `config/initializers/cmdx.rb` with default settings.
 
 ### Configuration Options
 

data/docs/getting_started.md

@@ -7,6 +7,7 @@ tasks to complex multi-step processes.
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Installation](#installation)
 - [Quick Setup](#quick-setup)
 - [Execution](#execution)
@@ -15,6 +16,16 @@ tasks to complex multi-step processes.
 - [Building Workflows](#building-workflows)
 - [Code Generation](#code-generation)
 
+## TLDR
+
+- **Installation** - Add `gem 'cmdx'` to Gemfile, run `rails g cmdx:install`
+- **Tasks** - Ruby classes inheriting from `CMDx::Task` with `call` method
+- **Execution** - Use `call` (returns result) or `call!` (raises on failure/skip)
+- **Parameters** - Define with `required`/`optional` with type coercion and validation
+- **Results** - Check `result.status` for success/skipped/failed outcomes
+- **Workflows** - Orchestrate multiple tasks with `CMDx::Workflow`
+- **Generators** - Use `rails g cmdx:task` and `rails g cmdx:workflow` for scaffolding
+
 ## Installation
 
 Add CMDx to your Gemfile:

data/docs/internationalization.md

@@ -0,0 +1,148 @@
+# Internationalization (i18n)
+
+CMDx provides comprehensive internationalization support for all error messages, including parameter coercion errors, validation failures, and fault messages. All error text is automatically localized based on the current `I18n.locale`.
+
+## Table of Contents
+
+- [TLDR](#tldr)
+- [Available Locales](#available-locales)
+- [Fault Messages](#fault-messages)
+- [Parameter Messages](#parameter-messages)
+- [Coercion Messages](#coercion-messages)
+- [Validation Messages](#validation-messages)
+
+## TLDR
+
+- **24 languages** - Built-in translations for major world languages
+- **Automatic localization** - Based on `I18n.locale` setting
+- **Complete coverage** - Coercion errors, validation failures, and fault messages
+- **Custom overrides** - Parameter-specific messages override locale defaults
+
+## Available Locales
+
+CMDx includes built-in translations for 24 languages:
+
+| Language | Locale | Language | Locale |
+|----------|--------|----------|--------|
+| English | `:en` | Russian | `:ru` |
+| Spanish | `:es` | Arabic | `:ar` |
+| French | `:fr` | Korean | `:ko` |
+| German | `:de` | Dutch | `:nl` |
+| Portuguese | `:pt` | Swedish | `:sv` |
+| Italian | `:it` | Hindi | `:hi` |
+| Japanese | `:ja` | Polish | `:pl` |
+| Chinese | `:zh` | Turkish | `:tr` |
+| Norwegian | `:no` | Danish | `:da` |
+| Finnish | `:fi` | Greek | `:el` |
+| Hebrew | `:he` | Thai | `:th` |
+| Vietnamese | `:vi` | Czech | `:cs` |
+
+## Fault Messages
+
+Default fault messages from `skip!` and `fail!` methods are localized:
+
+```ruby
+class ProcessPaymentTask < CMDx::Task
+  def call
+    # When no reason is provided, uses localized default
+    fail! if payment_declined?
+  end
+end
+
+# English
+I18n.locale = :en
+result = ProcessPaymentTask.call(payment_id: 123)
+result.metadata[:reason] #=> "no reason given"
+
+# Chinese
+I18n.locale = :zh
+result = ProcessPaymentTask.call(payment_id: 123)
+result.metadata[:reason] #=> "未提供原因"
+```
+
+## Parameter Messages
+
+Parameter required or undefined source errors are automatically localized:
+
+```ruby
+class ProcessOrderTask < CMDx::Task
+  required :order_id, type: :integer
+  optional :user_name, source: :nonexistent_method
+
+  def call
+    # Task implementation
+  end
+end
+
+# English locale
+I18n.locale = :en
+result = ProcessOrderTask.call({}) # Missing required parameter
+result.metadata[:messages][:order_id] #=> ["is a required parameter"]
+
+result = ProcessOrderTask.call(order_id: 123) # Undefined source method
+result.metadata[:messages][:user_name] #=> ["delegates to undefined method nonexistent_method"]
+
+# Spanish locale
+I18n.locale = :es
+result = ProcessOrderTask.call({}) # Missing required parameter
+result.metadata[:messages][:order_id] #=> ["es un parámetro requerido"]
+
+result = ProcessOrderTask.call(order_id: 123) # Undefined source method
+result.metadata[:messages][:user_name] #=> ["delegado al método indefinido nonexistent_method"]
+```
+
+## Coercion Messages
+
+Type conversion errors are automatically localized:
+
+```ruby
+class ProcessOrderTask < CMDx::Task
+  required :order_id, type: :integer
+  required :amount, type: :float
+
+  def call
+    # Task implementation
+  end
+end
+
+# English
+I18n.locale = :en
+result = ProcessOrderTask.call(order_id: "invalid", amount: "bad")
+result.metadata[:messages][:order_id] #=> ["could not coerce into an integer"]
+
+# Spanish
+I18n.locale = :es
+result = ProcessOrderTask.call(order_id: "invalid", amount: "bad")
+result.metadata[:messages][:order_id] #=> ["no podía coacciona el valor a un integer"]
+```
+
+## Validation Messages
+
+All validator error messages support internationalization:
+
+```ruby
+class RegisterUserTask < CMDx::Task
+  required :email, format: { with: /@/ }
+  required :age, numeric: { min: 18 }
+  required :status, inclusion: { in: %w[active inactive] }
+
+  def call
+    # Task implementation
+  end
+end
+
+# English
+I18n.locale = :en
+result = RegisterUserTask.call(email: "invalid", age: 16, status: "unknown")
+result.metadata[:messages][:email] #=> ["is an invalid format"]
+
+# Japanese
+I18n.locale = :ja
+result = RegisterUserTask.call(email: "invalid", age: 16, status: "unknown")
+result.metadata[:messages][:email] #=> ["無効な形式です"]
+```
+
+---
+
+- **Prev:** [Logging](logging.md)
+- **Next:** [Testing](testing.md)

data/docs/interruptions/exceptions.md

@@ -6,10 +6,19 @@ building reliable task execution flows and implementing proper error handling st
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Exception Handling Behavior](#exception-handling-behavior)
 - [Bang Call (`call!`)](#bang-call-call)
 - [Exception Classification](#exception-classification)
 
+## TLDR
+
+- **`call`** - Captures ALL exceptions, converts to failed results with metadata
+- **`call!`** - Lets exceptions propagate (except CMDx faults based on task_halt config)
+- **Exception info** - Available in `result.metadata[:original_exception]` and `result.metadata[:reason]`
+- **Guaranteed results** - `call` always returns a result object, never raises
+- **Fault vs Exception** - CMDx faults have special handling, other exceptions propagate in `call!`
+
 ## Exception Handling Behavior
 
 ### Non-bang Call (`call`)

data/docs/interruptions/faults.md

@@ -7,6 +7,7 @@ sophisticated exception handling and control flow patterns.
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Fault Types](#fault-types)
 - [Basic Exception Handling](#basic-exception-handling)
 - [Fault Context Access](#fault-context-access)
@@ -15,6 +16,14 @@ sophisticated exception handling and control flow patterns.
 - [Fault Chain Analysis](#fault-chain-analysis)
 - [Task Halt Configuration](#task-halt-configuration)
 
+## TLDR
+
+- **Fault types** - `CMDx::Skipped` (from `skip!`) and `CMDx::Failed` (from `fail!`)
+- **Exception handling** - Use `rescue CMDx::Fault` to catch both types
+- **Full context** - Faults provide access to `result`, `task`, `context`, and `chain`
+- **Advanced matching** - Use `for?(TaskClass)` and `matches? { |f| condition }` for specific fault handling
+- **Propagation** - Use `throw!(result)` to bubble up failures while preserving fault context
+
 ## Fault Types
 
 CMDx provides two primary fault types that inherit from the base `CMDx::Fault` class:

data/docs/interruptions/halt.md

@@ -6,6 +6,7 @@ outcomes, each serving specific use cases in business logic.
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Skip (`skip!`)](#skip-skip)
 - [Fail (`fail!`)](#fail-fail)
 - [Metadata Enrichment](#metadata-enrichment)
@@ -13,6 +14,14 @@ outcomes, each serving specific use cases in business logic.
 - [Exception Behavior](#exception-behavior)
 - [The Reason Key](#the-reason-key)
 
+## TLDR
+
+- **`skip!`** - Controlled interruption when task shouldn't execute (not an error)
+- **`fail!`** - Controlled interruption when task encounters an error condition
+- **Metadata** - Both methods accept metadata hash: `skip!(reason: "...", error_code: "...")`
+- **State changes** - Both transition to `interrupted` state, `skipped` or `failed` status
+- **Exception behavior** - `call` returns results, `call!` raises `CMDx::Skipped/Failed` based on task_halt config
+
 ## Skip (`skip!`)
 
 The `skip!` method indicates that a task did not meet the criteria to continue

data/docs/logging.md

@@ -3,6 +3,7 @@
 CMDx provides comprehensive automatic logging for task execution with structured data, customizable formatters, and intelligent severity mapping. All task results are logged after completion with rich metadata for debugging and monitoring.
 
 ## Table of Contents
+- [TLDR](#tldr)
 - [Log Formatters](#log-formatters)
   - [Standard Formatters](#standard-formatters)
   - [Stylized Formatters (ANSI Colors)](#stylized-formatters-ansi-colors)
@@ -22,6 +23,15 @@ CMDx provides comprehensive automatic logging for task execution with structured
   - [Multi-Destination Logging](#multi-destination-logging)
 - [Log Data Structure](#log-data-structure)
 
+## TLDR
+
+- **Automatic logging** - All task results logged after completion with structured data
+- **8 formatters** - Standard (Line, Json, KeyValue, Logstash, Raw) and Stylized (Pretty variants)
+- **Configuration** - Global via `CMDx.configure` or task-specific via `task_settings!`
+- **Severity mapping** - Success=INFO, Skipped=WARN, Failed=ERROR
+- **Rich metadata** - Includes runtime, chain_id, status, context, and failure chains
+- **Manual logging** - Access `logger` within tasks for custom messages
+
 ## Log Formatters
 
 CMDx provides 8 built-in log formatters organized into standard and stylized categories:
@@ -242,4 +252,4 @@ CMDx logs contain comprehensive execution metadata:
 ---
 
 - **Prev:** [Workflows](workflows.md)
-- **Next:** [Testing](testing.md)
+- **Next:** [Internationalization (i18n)](internationalization.md)