docs: restructure README and polish documentation

- Put Quick Start before Features; condense feature list and add Philosophy section
- Rename composer analyse script to analyze (CI and AGENTS.md updated)
- Use em dashes in Markdown; limit ASCII punctuation rule to PHP code in AGENTS.md
- Fix README examples (nullifyEmpty before email, minLength for passwords)
- Replace satisfies() strlen examples with digit-count custom code examples

Author: lemmon

.github/workflows/ci.yml

@@ -49,7 +49,7 @@ jobs:
         run: composer lint
 
       - name: Static analysis
-        run: composer analyse
+        run: composer analyze
 
       - name: Tests
         run: composer test

AGENTS.md

@@ -25,9 +25,9 @@ Core validation logic lives in `src/Lemmon/Validator/`. Tests in `tests/` follow
 
 - `composer test` - Run Pest test suite
 - `composer lint` / `composer format` - Mago linting and formatting (dev dependency)
-- `composer analyse` - PHPStan at max level
+- `composer analyze` - PHPStan at max level
 - `composer platform-check` - Verify PHP 8.3 and extension requirements
-- `composer check` - Run all checks (platform, format, lint, Prettier, test, analyse); use before PR
+- `composer check` - Run all checks (platform, format, lint, Prettier, test, analyze); use before PR
 - `npm run format` - Prettier for YAML, JSON, Markdown
 - `npm run check` - Alias for `composer check`
 - Pre-commit hook (Husky): Prettier check, Mago format --staged, Mago lint --staged
@@ -38,4 +38,4 @@ Dev tooling: symfony/var-dumper, symfony/error-handler, ergebnis/composer-normal
 
 ## Coding Style & Formatting
 
-PSR-12 for PHP. Mago for lint/format (`composer lint`, `composer format`). Prettier (`.prettierrc`) for YAML, JSON, Markdown. Add PHPDoc where behavior is non-obvious. Stick to ASCII punctuation in code and docs (e.g. `--` not em dash) so diffs stay predictable. Emojis sparingly.
+PSR-12 for PHP. Mago for lint/format (`composer lint`, `composer format`). Prettier (`.prettierrc`) for YAML, JSON, Markdown. Add PHPDoc where behavior is non-obvious. Stick to ASCII punctuation in PHP code (e.g. `--`, not an em dash); Markdown and other docs may use proper typographic characters.

CHANGELOG.md

@@ -44,16 +44,16 @@ All notable changes to this project will be documented in this file.
 
 ### Fixed
 
-- **CRITICAL BUG**: Fixed `default()` and `required()` interaction -- `required()` was rejecting null values before `default()` had a chance to provide a fallback
+- **CRITICAL BUG**: Fixed `default()` and `required()` interaction — `required()` was rejecting null values before `default()` had a chance to provide a fallback
   - **Issue**: Chaining `->default($value)->required()` always threw "Value is required" for null inputs because `required` checked for null before `default` was applied
   - **Root Cause**: `tryValidate()` had a scattered, multi-branch architecture with `default` and `required` checks duplicated across 5+ locations (early returns, pre-pipeline, mid-loop, post-loop), making the interaction order unpredictable
   - **Fix**: Simplified `tryValidate()` to a clean linear 5-step flow: coerce, type check, pipeline, default, required
-  - **Impact**: `default()` and `required()` now work cooperatively -- `default()` is the last-resort fallback for null, `required()` only fails if the value is still null after default
+  - **Impact**: `default()` and `required()` now work cooperatively — `default()` is the last-resort fallback for null, `required()` only fails if the value is still null after default
   - **Real-World Benefit**: Enables patterns like `->pipe(fn($x) => null)->default($fallback)->required()` where a pipeline step intentionally nullifies a value and `default()` catches it before `required()` enforces presence
 
 ### Changed
 
-- **Simplified `tryValidate()` pipeline architecture** -- reduced from 67 lines with 5+ branch points to 33 lines with a linear flow
+- **Simplified `tryValidate()` pipeline architecture** — reduced from 67 lines with 5+ branch points to 33 lines with a linear flow
   - Removed 2 duplicated early returns for null + no-pipeline + not-required
   - Removed mid-loop `default()` and `required()` checks (were duplicating post-loop logic)
   - `default()` now applies in exactly one place: after the pipeline, as the last-resort fallback

README.md

@@ -17,43 +17,6 @@ composer require lemmon/validator
 
 **Requirements:** PHP 8.3 or higher
 
-## About
-
-**Philosophy: "Simple and Minimal with Extensibility Over Reinvention"**
-
-Rather than reimplementing every possible transformation or validation rule, Lemmon Validator provides a solid foundation with generic `transform()` and `pipe()` methods that integrate seamlessly with PHP's ecosystem. Need complex string transformations? Plug in Laravel's `Str` class through our transformation system. Need advanced array operations? Connect Laravel Collections via our fluent API. The library focuses on what it does best: type-safe validation with excellent developer experience, while enabling you to leverage the entire PHP ecosystem.
-
-**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()`. `transform()` and `pipe()` skip `null` by default for type safety. Use `transform($fn, skipNull: false)` to process null values.
-- **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()`
-- **Last-Resort Default**: `default()` is a flag applied after the pipeline -- fills in null only as a last resort, before `required()` enforces presence
-- **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);`, 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()`, `transform()`/`pipe()`/`nullifyEmpty()` skip `null` by default
-- **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
-- **Schema-level error aggregation** with fail-fast behavior per field for clear, early feedback
-- **Structured errors** - `getStructuredErrors()` returns `ValidationError` objects with a stable `code` (see `ValidationCode`), dotted `path`, `message`, and `params` for programmatic handling and i18n; match on codes rather than message text
-- **API-friendly flattened errors** with field paths for easy frontend integration (`getFlattenedErrors()`, `ValidationException::flattenErrors()`)
-- **Intuitive custom validation** with `satisfies()` method and optional error messages
-- **Single-value validation** with `const()` for exact value matching (available on all validators)
-- **PHP enum validation** with `enum()` for `BackedEnum` (backed values) and `UnitEnum` (case instances or string case names) (available on all validators)
-- **Logical combinators** (`Validator::allOf()`, `Validator::anyOf()`, `Validator::not()`) for complex validation logic
-- **Form-safe coercion** - empty strings become `null` (not dangerous `0`/`false`) for real-world safety
-- **Accurate schema validation** - results only include provided fields and fields with defaults (no unexpected properties)
-- **Universal transformations** (`transform()`, `pipe()`) for post-validation data processing
-- **Null-safe operations** with `nullifyEmpty()` method for consistent empty value handling
-
 ## Quick Start
 
 All runtime classes live under the `Lemmon\Validator` namespace.
@@ -63,16 +26,16 @@ use Lemmon\Validator\Validator;
 
 // Simple validation with form-safe coercion
 $email = Validator::isString()
-    ->email()
     ->nullifyEmpty() // Empty strings become null (form-safe)
+    ->email()
     ->validate('user@example.com');
 
 // Schema validation with custom logic
 $userSchema = Validator::isAssociative([
     'name' => Validator::isString()->required(),
     'age' => Validator::isInt()->min(18)->coerce(),
-    'email' => Validator::isString()->email()->nullifyEmpty(),
-    'password' => Validator::isString()->satisfies(fn($v) => strlen($v) >= 8, 'Password too short')
+    'email' => Validator::isString()->nullifyEmpty()->email(),
+    'password' => Validator::isString()->minLength(8, 'Password too short')
 ]);
 
 // Tuple-based validation (no exceptions)
@@ -91,6 +54,26 @@ try {
 }
 ```
 
+## Features
+
+- **Type-safe validation** for strings, integers, floats, arrays, and objects, powered by PHP enums for IDE autocomplete, refactoring safety, and zero magic strings
+- **Fluent, chainable API** with a guaranteed execution order — methods run exactly as written (`->pipe('trim')->nullifyEmpty()->required()`)
+- **Smart null handling** — validations skip `null` unless `required()`; `transform()`/`pipe()`/`nullifyEmpty()` skip `null` by default
+- **Form-safe coercion** — empty strings become `null` (not dangerous `0`/`false`); opt into `coerce()` for form-friendly type conversions
+- **Universal transformations** (`transform()`, `pipe()`) that plug in any PHP callable or external library
+- **Custom validation** with `satisfies()`, plus logical combinators (`satisfiesAll()`/`satisfiesAny()`/`satisfiesNone()`)
+- **Exact-value and enum matching** — `const()` for single values, `enum()` for `BackedEnum`/`UnitEnum` (available on all validators)
+- **Last-resort defaults** — `default()` fills `null` after the pipeline, before `required()` enforces presence
+- **Structured errors** — `getStructuredErrors()` returns `ValidationError` objects with a stable `code` (see `ValidationCode`), dotted `path`, `message`, and `params` for programmatic handling and i18n
+- **Fail-fast per field, aggregated per schema** — each validator stops at its first failure while schema validation collects errors across all fields
+- **API-friendly flattened errors** with field paths (`_root` for root, dot notation for nested) via `getFlattenedErrors()`
+- **Accurate schema results** — output includes only provided fields and fields with defaults, never unexpected properties
+- **Strict typing throughout** — every file uses `declare(strict_types=1);`
+
+## Philosophy
+
+**Simple and minimal, with extensibility over reinvention.** Rather than reimplementing every possible transformation or validation rule, Lemmon Validator provides a solid foundation with generic `transform()` and `pipe()` methods that integrate seamlessly with PHP's ecosystem. Need complex string transformations? Plug in Laravel's `Str` class. Need advanced array operations? Connect Laravel Collections. The library focuses on what it does best — type-safe validation with excellent developer experience — while letting you leverage the entire PHP ecosystem.
+
 ## Documentation
 
 ### Getting Started
@@ -101,12 +84,12 @@ try {
 
 ### Validation Guides
 
-- [String Validation](docs/guides/string-validation.md) -- Email, URL, patterns, length constraints
-- [Numeric Validation](docs/guides/numeric-validation.md) -- Integers, floats, ranges, constraints
-- [Array Validation](docs/guides/array-validation.md) -- Indexed arrays and item validation
-- [Object & Schema Validation](docs/guides/object-validation.md) -- Complex nested structures
-- [Custom Validation](docs/guides/custom-validation.md) -- User-defined functions and business logic
-- [Error Handling](docs/guides/error-handling.md) -- Working with validation errors
+- [String Validation](docs/guides/string-validation.md) — Email, URL, patterns, length constraints
+- [Numeric Validation](docs/guides/numeric-validation.md) — Integers, floats, ranges, constraints
+- [Array Validation](docs/guides/array-validation.md) — Indexed arrays and item validation
+- [Object & Schema Validation](docs/guides/object-validation.md) — Complex nested structures
+- [Custom Validation](docs/guides/custom-validation.md) — User-defined functions and business logic
+- [Error Handling](docs/guides/error-handling.md) — Working with validation errors
 
 ### API Reference
 

composer.json

@@ -50,14 +50,14 @@
         "sort-packages": true
     },
     "scripts": {
-        "analyse": "phpstan analyse",
+        "analyze": "phpstan analyse",
         "check": [
             "@platform-check",
             "mago format --check",
             "@lint",
             "npm run format:check",
             "@test",
-            "@analyse"
+            "@analyze"
         ],
         "format": "mago format",
         "lint": "mago lint",

docs/api-reference/validator-factory.md

@@ -732,7 +732,7 @@ $validator = Validator::isObject()->defaultUsing(
 $result = $validator->validate(null); // Returns a new stdClass each time
 ```
 
-Use this whenever the default contains mutable objects -- whether a plain object or an array with nested objects. Each call to `validate()` will invoke the factory and receive a fresh instance.
+Use this whenever the default contains mutable objects — whether a plain object or an array with nested objects. Each call to `validate()` will invoke the factory and receive a fresh instance.
 
 ---
 

docs/examples/form-validation.md

@@ -883,7 +883,7 @@ class FileUploadValidator
 
 ## Next Steps
 
-- [String Validation Guide](../guides/string-validation.md) -- Advanced string validation patterns
-- [Numeric Validation Guide](../guides/numeric-validation.md) -- Numeric validation techniques
-- [Object & Schema Validation](../guides/object-validation.md) -- Complex nested structure validation
-- [Error Handling Guide](../guides/error-handling.md) -- Advanced error handling techniques
+- [String Validation Guide](../guides/string-validation.md) — Advanced string validation patterns
+- [Numeric Validation Guide](../guides/numeric-validation.md) — Numeric validation techniques
+- [Object & Schema Validation](../guides/object-validation.md) — Complex nested structure validation
+- [Error Handling Guide](../guides/error-handling.md) — Advanced error handling techniques

docs/getting-started/basic-usage.md

@@ -154,7 +154,7 @@ $result = $safeQuantity->validate('5'); // Returns: 5
 
 ### Execution Order Matters
 
-**Critical**: Pipeline steps execute in the **exact order written**. This matters for `pipe()`, `transform()`, and `nullifyEmpty()`. Both `required()` and `default()` are flags -- their position does not change execution order. `default()` fills in null after the pipeline as a last resort; `required()` enforces presence at the very end.
+**Critical**: Pipeline steps execute in the **exact order written**. This matters for `pipe()`, `transform()`, and `nullifyEmpty()`. Both `required()` and `default()` are flags — their position does not change execution order. `default()` fills in null after the pipeline as a last resort; `required()` enforces presence at the very end.
 
 ```php
 // Order matters for transformations
@@ -347,7 +347,7 @@ $withFallback = Validator::isString()
 
 ## Next Steps
 
-- [Core Concepts](core-concepts.md) -- Understand the architecture
-- [String Validation Guide](../guides/string-validation.md) -- Detailed string validation
-- [Numeric Validation Guide](../guides/numeric-validation.md) -- Integer and float validation
-- [Custom Validation Guide](../guides/custom-validation.md) -- Create your own validation rules
+- [Core Concepts](core-concepts.md) — Understand the architecture
+- [String Validation Guide](../guides/string-validation.md) — Detailed string validation
+- [Numeric Validation Guide](../guides/numeric-validation.md) — Integer and float validation
+- [Custom Validation Guide](../guides/custom-validation.md) — Create your own validation rules

docs/getting-started/core-concepts.md

@@ -124,12 +124,12 @@ Validator::isObject($schema)            // stdClass object with schema
 Understanding the validation flow helps debug and optimize your validators:
 
 1. **Type Coercion** - If enabled, attempt type conversion (empty strings become `null` for primitives)
-2. **Type Validation** - Check value type (skipped for null -- lets the pipeline and default/required handle it)
+2. **Type Validation** - Check value type (skipped for null — lets the pipeline and default/required handle it)
 3. **Pipeline Execution** - Validations and transformations run in the order written (fail-fast per field)
 4. **Default** - Last-resort fallback: if the result is null and a default exists, apply it
 5. **Required** - Single check, always last: if the value is still null after default, fail
 
-`default()` and `required()` are both flags -- their position in the fluent chain does not change when they are evaluated. `default()` always applies after the pipeline as the last-resort fallback for null. `required()` always enforces presence at the very end, after default has had its chance.
+`default()` and `required()` are both flags — their position in the fluent chain does not change when they are evaluated. `default()` always applies after the pipeline as the last-resort fallback for null. `required()` always enforces presence at the very end, after default has had its chance.
 
 ## Data Transformations
 
@@ -258,7 +258,7 @@ $processed = Validator::isArray()
 
 ### Transformation Pipeline Order
 
-Pipeline methods (`pipe()`, `transform()`, `nullifyEmpty()`, `satisfies()`, etc.) execute in their written order. `required()` and `default()` are flags -- their position does not change execution order:
+Pipeline methods (`pipe()`, `transform()`, `nullifyEmpty()`, `satisfies()`, etc.) execute in their written order. `required()` and `default()` are flags — their position does not change execution order:
 
 ```php
 // Execution order: trim → nullifyEmpty
@@ -498,7 +498,7 @@ $email2 = $emailValidator->validate('user2@example.com');
 
 Now that you understand the core concepts:
 
-- [String Validation Guide](../guides/string-validation.md) -- Master string validation
-- [Numeric Validation Guide](../guides/numeric-validation.md) -- Work with numbers
-- [Object & Schema Validation](../guides/object-validation.md) -- Handle complex structures
-- [Custom Validation Guide](../guides/custom-validation.md) -- Create custom business rules
+- [String Validation Guide](../guides/string-validation.md) — Master string validation
+- [Numeric Validation Guide](../guides/numeric-validation.md) — Work with numbers
+- [Object & Schema Validation](../guides/object-validation.md) — Handle complex structures
+- [Custom Validation Guide](../guides/custom-validation.md) — Create custom business rules

docs/getting-started/installation.md

@@ -78,11 +78,11 @@ composer lint
 composer fix
 
 # Run static analysis
-composer analyse
+composer analyze
 ```
 
 ## Next Steps
 
-- [Basic Usage](basic-usage.md) -- Learn the fundamentals
-- [Core Concepts](core-concepts.md) -- Understand the architecture
-- [String Validation Guide](../guides/string-validation.md) -- Start with string validation
+- [Basic Usage](basic-usage.md) — Learn the fundamentals
+- [Core Concepts](core-concepts.md) — Understand the architecture
+- [String Validation Guide](../guides/string-validation.md) — Start with string validation