docs: review and clarify all documentation

Author: lemmon

AGENTS.md

@@ -9,7 +9,7 @@ A comprehensive, fluent validation library for PHP inspired by Valibot and Zod.
 ### Core Factory Pattern
 - **`Validator`** - Static factory creating type-specific validators (`isString()`, `isInt()`, `isFloat()`, `isArray()`, `isAssociative()`, `isObject()`, `isBool()`)
 - **`FieldValidator`** - Abstract base class with unified validation interface and shared functionality
-- **`ValidationException`** - Structured exception handling with comprehensive error collection
+- **`ValidationException`** - Structured exception handling with aggregated error reporting
 
 ### Type-Specific Validators
 - **`StringValidator`** - Format validation (email, URL, UUID with version variants, IP with version variants, hostname, domain, time, base64 with variants, hex), length constraints, pattern matching
@@ -29,14 +29,14 @@ A comprehensive, fluent validation library for PHP inspired by Valibot and Zod.
 - **Static Logical Combinators** - `Validator::allOf()`, `Validator::anyOf()`, `Validator::not()` for complex rule composition and mixed-type validation
 - **New `satisfies*` API** - Enhanced instance logical combinators (`satisfiesAny()`, `satisfiesAll()`, `satisfiesNone()`) with support for mixed validators/callables
 - **Enum-Based Variant Flags** - Type-safe variant selection for IP addresses (`IpVersion`), Base64 encoding (`Base64Variant`), and UUID versions (`UuidVariant`) with consistent API pattern
-- **Smart Null Handling** - Revolutionary null handling system where validations skip `null` unless `required()`, transformations always execute, and order is independent
+- **Smart Null Handling** - Validations skip `null` unless `required()`. `transform()` runs on `null`, while `pipe()` and `nullifyEmpty()` skip `null` for type safety.
 - **Form-Safe Coercion** - Empty strings convert to `null` (not dangerous `0`/`0.0`/`false`) for primitives, empty structures for objects/arrays
 - **Array Filtering** - `filterEmpty()` method removes empty values while maintaining indexed array structure
 - **Type-Aware Transformations** - Revolutionary `transform()` and `pipe()` system with intelligent type context switching
-- **Unified Pipeline Architecture** - Single conceptual pipeline with hybrid execution (error collection for validations, fail-fast for transformations)
+- **Unified Pipeline Architecture** - Single conceptual pipeline with ordered execution and fail-fast behavior per field
 - **Custom Validation** - Enhanced `satisfies()` method accepting `FieldValidator` instances or callables with optional error messages (all internal validators migrated from deprecated `addValidation()`)
 - **Context-Aware Validation** - Custom validators receive `(value, key, input)` parameters
-- **Comprehensive Error Collection** - All validation errors collected, not just the first failure
+- **Fail-Fast Per Field** - Each validator stops at the first failing rule, while schema validation aggregates errors across fields
 - **Smart Type Coercion** - Configurable automatic type conversion with form-friendly defaults
 - **Fluent API with guaranteed execution order** - Chainable method calls that execute in the exact order written
 - **Extensibility Philosophy** - Focus on core validation principles; external libraries encouraged for advanced/specialized validators via `satisfies()`

CHANGELOG.md

@@ -4,6 +4,9 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Documentation
+- Clarified fail-fast behavior per field and schema-level error aggregation in guides and examples
+
 ## [0.11.2] - 2026-01-05
 
 ### Fixed

CONTRIBUTING.md

@@ -4,7 +4,7 @@ Contributions are welcome! Please feel free to submit a pull request.
 
 ## Development
 
-To get started, you will need to have PHP 8.4+ and Composer installed.
+To get started, you will need to have PHP 8.3+ and Composer installed.
 
 1.  Fork the repository and clone it to your local machine.
 2.  Install the dependencies:

README.md

@@ -26,22 +26,22 @@ Rather than reimplementing every possible transformation or validation rule, Lem
 **Key Design Principles:**
 
 - **Type-Safe Architecture**: Modern PHP 8.1+ enums provide IDE autocomplete, refactoring safety, and eliminate magic strings throughout the codebase
-- **Smart Null Handling**: Validations skip `null` unless `required()`, transformations always execute, and method order is independent for intuitive behavior
+- **Smart Null Handling**: Validations skip `null` unless `required()`. `transform()` runs on `null`, while `pipe()` and `nullifyEmpty()` skip `null` for type safety.
 - **Form Safety First**: Empty strings coerce to `null` (not dangerous `0`/`false`) to prevent real-world issues like accidental zero bank balances
 - **Fluent API with Execution Order Guarantee**: Validation rules read like natural language and execute in the exact order written -- `Validator::isString()->pipe('trim')->nullifyEmpty()->required()`
-- **Comprehensive Error Collection**: All validation errors are collected, not just the first failure
+- **Fail-Fast Per Field**: Each validator stops at the first failing rule, while schema validation still aggregates errors across fields
 - **API-Friendly Error Format**: Flattened errors with field paths (`'_root'` for root-level, dot notation for nested) perfect for frontend consumption
 - **Type-Aware Transformations**: Intelligent transformation system that maintains type context and handles coercion automatically
 - **Extensible Architecture**: Generic transformation methods work with any PHP callable or external library
-- **Strict Typing**: All files use `declare(strict_types=1);`, so scalar mismatches raise clear errors; opt into `coerce()` when you need form-friendly conversions.
+- **Strict Typing**: All files use `declare(strict_types=1);`, keeping internal type hints strict; opt into `coerce()` when you need form-friendly conversions.
 
 ## Features
 
 - **Type-safe architecture** - PHP 8.1+ enums with IDE autocomplete, refactoring safety, and zero magic strings
-- **Smart null handling** - validations skip `null` unless `required()`, transformations always execute, order-independent behavior
+- **Smart null handling** - validations skip `null` unless `required()`, `transform()` runs on `null`, `pipe()`/`nullifyEmpty()` skip `null`
 - **Type-safe validation** for strings, integers, floats, arrays, and objects
 - **Fluent, chainable API** with guaranteed execution order -- methods execute exactly as written in the chain
-- **Comprehensive error collection** with detailed, structured feedback
+- **Schema-level error aggregation** with fail-fast behavior per field for clear, early feedback
 - **API-friendly flattened errors** with field paths for easy frontend integration (`getFlattenedErrors()`, `ValidationException::flattenErrors()`)
 - **Intuitive custom validation** with `satisfies()` method and optional error messages
 - **Logical combinators** (`Validator::allOf()`, `Validator::anyOf()`, `Validator::not()`) for complex validation logic

ROADMAP.md

@@ -8,6 +8,10 @@ This roadmap outlines the strategic development plan for future releases, priori
 
 **Core Principle:** Validate first, transform with the best tools available.
 
+## Current Behavior Notes
+
+- Validation fails fast per field; schema validation still aggregates errors across fields.
+
 ## Recently Completed
 
 ### Flattened Errors for API Consumption (Current)

docs/api-reference/validator-factory.md

@@ -5,15 +5,15 @@ The `Validator` class serves as the main entry point and factory for creating va
 ## Class Overview
 
 ```php
-namespace Lemmon;
+namespace Lemmon\Validator;
 
 class Validator
 {
     // Factory methods for creating specific validators
     public static function isString(): StringValidator
     public static function isInt(): IntValidator
     public static function isFloat(): FloatValidator
-    public static function isArray(?FieldValidator $itemValidator = null): ArrayValidator
+    public static function isArray(): ArrayValidator
     public static function isAssociative(array $schema = []): AssociativeValidator
     public static function isObject(array $schema = []): ObjectValidator
     public static function isBool(): BoolValidator
@@ -79,7 +79,7 @@ $percentageValidator = Validator::isFloat()->min(0.0)->max(100.0);
 
 ---
 
-### `isArray(?FieldValidator $itemValidator = null): ArrayValidator`
+### `isArray(): ArrayValidator`
 
 Creates a validator for indexed arrays.
 
@@ -89,7 +89,7 @@ $validator = Validator::isArray();
 $result = $validator->validate([1, 2, 3]); // Returns: [1, 2, 3]
 
 // Array with item validation
-$numbersValidator = Validator::isArray(
+$numbersValidator = Validator::isArray()->items(
     Validator::isInt()->positive()
 );
 $numbers = $numbersValidator->validate([1, 2, 3]); // Each item validated as positive int
@@ -100,9 +100,6 @@ $emailsValidator = Validator::isArray()->items(
 );
 ```
 
-**Parameters:**
-- `$itemValidator` (optional): `FieldValidator` instance to validate each array item
-
 **Returns:** `ArrayValidator` instance with array-specific validation methods.
 
 **See Also:** [Array Validation Guide](../guides/array-validation.md)
@@ -242,7 +239,7 @@ $orderValidator = Validator::isAssociative([
         'email' => Validator::isString()->email()->required(),
         'phone' => Validator::isString()->pattern('/^\+?[1-9]\d{1,14}$/')
     ])->required(),
-    'items' => Validator::isArray(
+    'items' => Validator::isArray()->items(
         Validator::isAssociative([
             'product_id' => Validator::isInt()->positive()->required(),
             'quantity' => Validator::isInt()->min(1)->required(),

docs/examples/form-validation.md

@@ -123,26 +123,19 @@ if ($_SERVER['REQUEST_METHOD'] === 'POST') {
 
 ### The Problem with Empty Form Fields
 
-HTML forms often submit empty strings for unfilled fields, which can create dangerous scenarios:
+HTML forms often submit empty strings for unfilled fields. In plain PHP casting (or legacy behavior), empty strings can become dangerous defaults:
 
 ```php
-// ❌ DANGEROUS: Without nullifyEmpty()
-$orderValidator = Validator::isAssociative([
-    'quantity' => Validator::isInt()->coerce(), // Empty string → 0 (dangerous!)
-    'price' => Validator::isFloat()->coerce(),  // Empty string → 0.0 (dangerous!)
-    'discount' => Validator::isFloat()->coerce()->default(5.0), // Empty → 0.0, not 5.0!
-]);
-
-// Form data with empty fields
+// ❌ DANGEROUS: Plain PHP casting
 $formData = [
     'quantity' => '', // Empty field from form
     'price' => '',    // Empty field from form
     'discount' => '', // Empty field from form
 ];
 
-$result = $orderValidator->validate($formData);
-// Result: ['quantity' => 0, 'price' => 0.0, 'discount' => 0.0]
-// ❌ All dangerous zero values!
+$quantity = (int) $formData['quantity']; // 0 (dangerous!)
+$price = (float) $formData['price']; // 0.0 (dangerous!)
+$discount = (float) ($formData['discount'] ?? 5.0); // 0.0, not 5.0!
 ```
 
 ### The Solution: Form-Safe Validation
@@ -155,11 +148,13 @@ $safeOrderValidator = Validator::isAssociative([
     'quantity' => Validator::isInt()
         ->coerce()
         ->nullifyEmpty() // Empty strings → null
+        ->required('Quantity is required')
         ->min(1, 'Quantity must be at least 1'), // Validation fails for null (safe!)
 
     'price' => Validator::isFloat()
         ->coerce()
         ->nullifyEmpty() // Empty strings → null
+        ->required('Price is required')
         ->positive('Price must be positive'), // Validation fails for null (safe!)
 
     'discount' => Validator::isFloat()
@@ -329,7 +324,7 @@ class UserRegistrationValidator
             // Demographics
             'date_of_birth' => Validator::isString()
                 ->required('Date of birth is required')
-                ->date('Please enter a valid date (YYYY-MM-DD)')
+                ->date('Y-m-d', 'Please enter a valid date (YYYY-MM-DD)')
                 ->satisfies(
                     function ($date) {
                         $birthDate = new DateTime($date);
@@ -567,7 +562,7 @@ class ProductFormValidator
             'allow_backorder' => Validator::isBool()->coerce()->default(false),
 
             // Categories and Tags
-            'category_ids' => Validator::isArray(
+            'category_ids' => Validator::isArray()->items(
                 Validator::isInt()->positive()
             )
             ->required('At least one category is required')
@@ -580,7 +575,7 @@ class ProductFormValidator
                 'One or more selected categories do not exist'
             ),
 
-            'tags' => Validator::isArray(
+            'tags' => Validator::isArray()->items(
                 Validator::isString()
                     ->minLength(2, 'Tags must be at least 2 characters')
                     ->maxLength(30, 'Tags cannot exceed 30 characters')
@@ -600,7 +595,7 @@ class ProductFormValidator
                 ->default('draft'),
 
             'published_at' => Validator::isString()
-                ->datetime('Please enter a valid date and time')
+                ->datetime('Y-m-d\TH:i:s', 'Please enter a valid date and time')
                 ->satisfies(
                     function ($datetime, $key, $input) {
                         if ($input['status'] === 'active' && !$datetime) {
@@ -627,7 +622,7 @@ class ProductFormValidator
             // Digital Products
             'is_digital' => Validator::isBool()->coerce()->default(false),
 
-            'download_files' => Validator::isArray(
+            'download_files' => Validator::isArray()->items(
                 Validator::isAssociative([
                     'name' => Validator::isString()->required(),
                     'url' => Validator::isString()->url()->required(),
@@ -713,7 +708,7 @@ class MultiStepRegistrationValidator
 
             'date_of_birth' => Validator::isString()
                 ->required('Date of birth is required')
-                ->date('Please enter a valid date')
+                ->date('Y-m-d', 'Please enter a valid date')
         ]);
 
         return $this->validateStep($validator, $data);

docs/getting-started/basic-usage.md

@@ -136,9 +136,10 @@ $result = $optional->validate('John');    // Returns: 'John'
 $safeQuantity = Validator::isInt()
     ->coerce()
     ->nullifyEmpty()     // Empty strings → null (not dangerous 0)
+    ->required('Quantity is required')
     ->min(1, 'Quantity must be at least 1');
 
-$result = $safeQuantity->validate(''); // Validation fails (safe!)
+$result = $safeQuantity->validate(''); // ❌ "Quantity is required" (safe!)
 $result = $safeQuantity->validate('5'); // Returns: 5
 ```
 
@@ -150,23 +151,21 @@ $result = $safeQuantity->validate('5'); // Returns: 5
 
 ### Execution Order Matters
 
-**Critical**: Methods execute in the **exact order written**. This is especially important when combining transformations with `required()`:
+**Critical**: Pipeline steps execute in the **exact order written**. This matters for `pipe()`, `transform()`, and `nullifyEmpty()`. `required()` is a flag, so its position does not change execution order.
 
 ```php
-// CORRECT: Trim → nullify → require (fails on empty input)
-$requiredName = Validator::isString()
+// Order matters for transformations
+$trimThenNullify = Validator::isString()
     ->pipe('trim')        // 1. Remove whitespace
-    ->nullifyEmpty()      // 2. Empty strings → null
-    ->required('Name is required'); // 3. Reject null values
+    ->nullifyEmpty();     // 2. Empty strings → null
 
-$requiredName->validate('    '); // ❌ "Name is required" (correct!)
+$trimThenNullify->validate('    '); // Returns: null
 
-// ❌ DIFFERENT BEHAVIOR: Require → nullify (allows empty input)
-$differentBehavior = Validator::isString()
-    ->required('Name is required') // 1. Check if empty string is null (passes)
-    ->nullifyEmpty();              // 2. Convert to null
+$nullifyThenTrim = Validator::isString()
+    ->nullifyEmpty()      // 1. Empty strings → null (only if already empty)
+    ->pipe('trim');       // 2. Trim whitespace
 
-$differentBehavior->validate(''); // Returns: null (different result!)
+$nullifyThenTrim->validate('    '); // Returns: '' (empty string)
 ```
 
 **Real-world form validation pattern:**
@@ -241,7 +240,7 @@ $validConfig = $configSchema->validate($config);
 ### Plain Arrays
 
 ```php
-$numbersValidator = Validator::isArray(
+$numbersValidator = Validator::isArray()->items(
     Validator::isInt()->min(0) // Each item must be a non-negative integer
 );
 
@@ -251,7 +250,7 @@ $validNumbers = $numbersValidator->validate($numbers);
 
 ## Error Handling
 
-Validation errors are collected comprehensively:
+Validation fails fast per field. Schema validation still collects errors across fields:
 
 ```php
 $validator = Validator::isString()
@@ -263,8 +262,7 @@ $validator = Validator::isString()
 
 // $errors might contain:
 // [
-//     'Value must be at least 5 characters long',
-//     'Value must be a valid email address'
+//     'Value must be at least 5 characters long'
 // ]
 ```