Update CHANGELOG.md

Author: pdphilip

CHANGELOG.md

@@ -6,14 +6,80 @@ All notable changes to this `laravel-elasticsearch` package will be documented i
 
 This release is compatible with Laravel 10, 11 & 12
 
-### Added
-- **Auto-create index on first query** — When a model queries an index that doesn't exist yet, the index is created automatically instead of throwing `index_not_found_exception`. Matches Elasticsearch's own auto-create behavior for writes, extended to reads. Controlled via `options.auto_create_index` config (default: `true`)
-- **Artisan commands** — `elastic:status`, `elastic:indices`, `elastic:show {index}` for connection health checks, index listing, and index inspection
-- **`upsert()`** — Insert or update records by unique key in a single bulk operation, matching Laravel's native `upsert()` signature. Supports single and batch documents, specific update columns, and composite unique keys
-- `TimeOrderedUUIDGenerator` — sortable 20-character IDs where lexicographic order matches chronological order across processes (millisecond granularity)
-- `GeneratesTimeOrderedIds` trait with `getRecordTimestamp()` and `getRecordDate()` helpers — safe for mixed datasets (returns null for pre-existing non-time-ordered IDs)
-- Schema Builder: `getIndexes()`, `getForeignKeys()`, `getViews()` for Laravel compatibility
-- Test suite expanded from 379 to 422 tests (2,548 assertions), all passing. New coverage: upsert variations, advanced aggregations, filter context queries, DSL output inspection, point-in-time pagination, multi-match search, time-ordered IDs
+[What's new in v5.4](https://elasticsearch.pdphilip.com/whats-new/#54-new-features)
+
+### New features
+
+#### Auto-Create Index
+
+When a model queries an index that doesn't exist yet, the index is created automatically instead of throwing `index_not_found_exception`. Matches Elasticsearch's own auto-create behavior for writes, extended to reads.
+
+```php
+// No migration needed - index is created on first query
+$products = Product::where('status', 'active')->get(); // returns empty collection
+```
+
+Controlled via `options.auto_create_index` config (default: `true`). - [Docs](https://elasticsearch.pdphilip.com/getting-started/)
+
+Why: New models shouldn't crash before the first write. Elasticsearch already auto-creates on insert; this extends the same behavior to reads.
+
+#### Artisan Commands
+
+First-class CLI tools for managing your Elasticsearch connection and indices:
+
+- `php artisan elastic:status` - Connection health check with cluster info and license details
+- `php artisan elastic:indices` - List all indices with health, doc count, and store size
+- `php artisan elastic:show {index}` - Inspect an index: overview, mappings, settings, and analysis config
+
+```bash
+php artisan elastic:status
+php artisan elastic:indices --all
+php artisan elastic:show products
+```
+
+All commands support `--connection=` for non-default connections.
+
+Why: Until now, inspecting your Elasticsearch setup meant leaving Laravel for curl or Kibana. These commands bring that visibility into Artisan where it belongs.
+
+#### Upsert
+
+New `upsert()` method matching Laravel's native signature. Insert or update records by unique key in a single bulk operation. - [Docs](https://elasticsearch.pdphilip.com/eloquent/saving-models/#upsert)
+
+```php
+Product::upsert(
+    [
+        ['sku' => 'ABC', 'name' => 'Widget', 'price' => 10],
+        ['sku' => 'DEF', 'name' => 'Gadget', 'price' => 20],
+    ],
+    ['sku'],           // unique key
+    ['name', 'price']  // columns to update if exists
+);
+```
+
+Supports single documents, batch operations, and composite unique keys.
+
+Why: Elasticsearch has no native upsert-by-field. This queries for existing documents first, then issues a single bulk request mixing index and update actions.
+
+#### Time-Ordered IDs
+
+New `GeneratesTimeOrderedIds` trait for sortable, chronologically-ordered IDs. 20 characters, URL-safe, lexicographic sort matches creation order across processes. - [Docs](https://elasticsearch.pdphilip.com/eloquent/the-base-model/#time-ordered-ids)
+
+```php
+use PDPhilip\Elasticsearch\Eloquent\GeneratesTimeOrderedIds;
+
+class TrackingEvent extends Model
+{
+    use GeneratesTimeOrderedIds;
+}
+
+$event->id;                    // "0B3kF5XRABCDE_fghijk"
+$event->getRecordTimestamp();  // 1771160093773 (ms)
+$event->getRecordDate();       // Carbon instance
+```
+
+Safe for mixed datasets; returns `null` for pre-existing IDs not generated by this trait.
+
+Why: When you need IDs that sort chronologically across multiple processes/workers, ideal for high-volume event tracking and time-sequenced analytics.
 
 ### Changed
 - Refactored Query Builder into focused concerns: `BuildsAggregations`, `BuildsSearchQueries`, `BuildsFieldQueries`, `BuildsGeoQueries`, `BuildsNestedQueries`, `HandlesScripts`, `ManagesPit`
@@ -23,16 +89,17 @@ This release is compatible with Laravel 10, 11 & 12
 - Consolidated metadata handling into single `MetaDTO`
 - Simplified `ManagesOptions` parameter inference
 - Extracted `addFieldQuery()` dispatcher in `BuildsFieldQueries` to deduplicate field query methods
-- Refactored Relations for readability: early returns, named variables, simplified loops across `MorphToMany`, `BelongsToMany`, `QueriesRelationships`, `InteractsWithPivotTable`, `ManagesManyToMany`
-- Updated `ModelDocs` with comprehensive audit: corrected signatures, added missing methods, removed stale entries
-- Added `declare(strict_types=1)` to all ID generation classes and traits
-- Consolidated test ID strategy into `TestsWithIdStrategies` trait (removed duplicate `WithIds/` and `IdGenerated/` directories)
+- Refactored Relations for readability: early returns, named variables, simplified loops
+- Schema Builder: added `getIndexes()`, `getForeignKeys()`, `getViews()` for Laravel compatibility
 - CI updated to Elasticsearch 8.18.0
+- Test suite expanded from 379 to 422 tests (2,548 assertions), all passing
 
 ### Fixed
 - `id` is now always present in serialized model output
 - Removed dead debug code from Connection.php
 
+**Full Changelog**: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.3.0...v5.4.0
+
 ## v5.3.0 - 2026-01-20
 
 This release is compatible with Laravel 10, 11 & 12