docs: comprehensive documentation update

- Update README.md with features list, requirements, and quick start example
- Add CLAUDE.md with project architecture and coding standards
- Expand doc/01-usage.md with more query building examples
- Update doc/02-query-objects.md with missing queries (PhrasePrefix, Nested, GeoDistance, Exists, MultiMatch)
- Update doc/03-aggregation-objects.md with missing aggregations (Min, Max, Avg, TopHits, Filter, Nested)
- Update doc/04-result-objects.md with ResultVersion and detailed usage examples
- Add doc/05-options.md for pagination, sorting, and scroll API
- Add doc/06-highlight-function-score.md for highlighting and custom scoring
- Add doc/07-mapping-settings.md for index mapping configuration

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: Spamercz

CLAUDE.md

@@ -0,0 +1,105 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+ElasticQuery is a PHP library that converts Elasticsearch query DSL into typed PHP objects. Instead of building queries as arrays, developers can use strongly-typed classes that mirror the Elasticsearch documentation.
+
+## Development Commands
+
+```bash
+# Install/update dependencies
+make composer
+
+# Run static analysis (PHPStan level 7)
+make phpstan
+
+# Run code style checks (Slevomat coding standard)
+make cs
+
+# Auto-fix code style issues
+make cbf
+
+# Run tests (Nette Tester)
+make tests
+
+# Run a single test file
+vendor/bin/tester -s -p php --colors 1 -C tests/SpameriTests/ElasticQuery/Path/To/Test.phpt
+```
+
+## Architecture
+
+### Core Query Building
+
+**ElasticQuery** (`src/ElasticQuery.php`) - Main entry point for building queries. Composes:
+- `QueryCollection` - Boolean query with must/should/mustNot collections
+- `FilterCollection` - Filter context queries
+- `AggregationCollection` - Aggregation definitions
+- `Options` - Pagination, sorting, scroll settings
+- `Highlight` - Search result highlighting
+- `FunctionScore` - Custom scoring functions
+
+All query/aggregation objects implement `toArray()` to serialize to Elasticsearch-compatible format.
+
+### Query Objects (`src/Query/`)
+
+Leaf queries implement `LeafQueryInterface`:
+- `ElasticMatch`, `MatchPhrase`, `MultiMatch`, `PhrasePrefix` - Full-text queries
+- `Term`, `Terms`, `Range`, `Exists`, `WildCard` - Term-level queries
+- `Nested`, `GeoDistance`, `Fuzzy` - Specialized queries
+
+Collection queries (`MustCollection`, `ShouldCollection`, `MustNotCollection`) also implement `LeafQueryInterface`, enabling nested boolean logic.
+
+### Aggregations (`src/Aggregation/`)
+
+- `LeafAggregationCollection` wraps aggregation definitions with nested sub-aggregations
+- Metric aggregations: `Min`, `Max`, `Avg`, `TopHits`
+- Bucket aggregations: `Term`, `Range`, `Histogram`, `Nested`, `Filter`
+
+### Response Mapping (`src/Response/`)
+
+`ResultMapper` converts Elasticsearch array responses to typed objects:
+- `ResultSearch` - Standard search results with hits and aggregations
+- `ResultSingle` - Single document retrieval
+- `ResultBulk` - Bulk operation results
+- `ResultVersion` - Cluster version info
+
+### Index Mapping (`src/Mapping/`)
+
+Classes for defining Elasticsearch index mappings:
+- Analyzers: Standard, custom dictionary analyzers for multiple languages
+- Filters: Stemming, synonyms, stop words, edge n-grams
+- Tokenizers: Pattern, whitespace, etc.
+- `Settings` - Index settings configuration
+
+### Document Handling (`src/Document.php`, `src/Document/`)
+
+`Document` wraps index name, body, and optional ID for Elasticsearch client calls.
+
+### Options & Sorting (`src/Options.php`, `src/Options/`)
+
+- `Options` - Pagination (size, from), scroll support, min_score, version inclusion
+- `Sort` - Field sorting with ASC/DESC and missing value handling
+- `GeoDistanceSort` - Geo-spatial sorting by distance from a point
+- `SortCollection` - Manages multiple sort criteria
+
+### Function Score (`src/FunctionScore.php`, `src/FunctionScore/`)
+
+Custom scoring with multiple score functions:
+- `FieldValueFactor` - Score based on numeric field values with modifiers (log, sqrt, etc.)
+- `Weight` - Constant weight multiplier when filter matches
+- `RandomScore` - Randomized scoring with optional seed for consistency
+
+Score modes: multiply, sum, avg, first, max, min
+
+## Coding Standards
+
+- PHP 8.2+ with strict types
+- Fully qualified class names in annotations
+- Fully qualified global functions and constants
+- Tab indentation (no spaces)
+- Trailing commas in arrays, function calls, and declarations
+- Constructor property promotion where applicable
+- No Yoda comparisons
+- Strict equality operators only (`===`, `!==`)

README.md

@@ -1,21 +1,65 @@
 # ElasticQuery
-Elastic documentation converted to php objects for easy using.
 
-Installation
-------------
+A PHP library that converts Elasticsearch query DSL into strongly-typed PHP objects. Instead of building queries as arrays, use type-safe classes that mirror the Elasticsearch documentation.
 
-The best way to install Spameri/ElasticQuery is using  [Composer](http://getcomposer.org/):
+## Features
+
+- **Type-safe queries** - Full-text, term-level, compound, geo, and nested queries
+- **Aggregations** - Metric (min, max, avg) and bucket (terms, histogram, range, filter) aggregations
+- **Response mapping** - Automatic mapping of Elasticsearch responses to typed objects
+- **Index mapping** - Define index settings, analyzers, tokenizers, and filters
+- **Function scoring** - Custom scoring with field value factors, weights, and random scores
+- **Highlighting** - Search result highlighting support
+- **Pagination & sorting** - Options for size, offset, scroll, and geo-distance sorting
+
+## Requirements
+
+- PHP 8.2 or higher
+
+## Installation
+
+Install via [Composer](http://getcomposer.org/):
 
 ```sh
-$ composer require spameri/elastic-query
+composer require spameri/elastic-query
 ```
 
-Documentation
-------------
+## Quick Start
+
+```php
+use Spameri\ElasticQuery\ElasticQuery;
+use Spameri\ElasticQuery\Query\ElasticMatch;
+use Spameri\ElasticQuery\Query\Term;
+
+// Create a query
+$query = new ElasticQuery();
+
+// Add a must query (AND condition)
+$query->addMustQuery(new ElasticMatch('title', 'Elasticsearch'));
+
+// Add a filter (cached, no scoring)
+$query->addFilter(new Term('status', 'published'));
+
+// Set pagination
+$query->options()->changeSize(10);
+$query->options()->changeFrom(0);
+
+// Convert to array for Elasticsearch client
+$body = $query->toArray();
+```
+
+## Documentation
+
+Learn more in the [documentation](https://github.com/Spameri/ElasticQuery/tree/master/doc):
+
+- [Usage](https://github.com/Spameri/ElasticQuery/tree/master/doc/01-usage.md) - Integration examples
+- [Query Objects](https://github.com/Spameri/ElasticQuery/tree/master/doc/02-query-objects.md) - All query types
+- [Aggregation Objects](https://github.com/Spameri/ElasticQuery/tree/master/doc/03-aggregation-objects.md) - Aggregation types
+- [Result Objects](https://github.com/Spameri/ElasticQuery/tree/master/doc/04-result-objects.md) - Response mapping
+- [Options & Sorting](https://github.com/Spameri/ElasticQuery/tree/master/doc/05-options.md) - Pagination, sorting, scroll
+- [Highlight & Function Score](https://github.com/Spameri/ElasticQuery/tree/master/doc/06-highlight-function-score.md) - Highlighting and custom scoring
+- [Mapping & Settings](https://github.com/Spameri/ElasticQuery/tree/master/doc/07-mapping-settings.md) - Index configuration
 
-Learn more in the [documentation](https://github.com/Spameri/ElasticQuery/tree/master/doc).
+## License
 
-- [Usage](https://github.com/Spameri/ElasticQuery/tree/master/doc/01-usage.md)
-- [Query objects](https://github.com/Spameri/ElasticQuery/tree/master/doc/02-query-objects.md)
-- [Aggregation objects](https://github.com/Spameri/ElasticQuery/tree/master/doc/03-aggregation-objects.md)
-- [Result objects](https://github.com/Spameri/ElasticQuery/tree/master/doc/04-result-objects.md)
+MIT