Improve docs

Author: cabol

AGENTS.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [v0.1.0](https://github.com/elixir-nebulex/nebulex_streams/tree/v0.1.0) (2025-11-11)
+> [Full Changelog](https://github.com/elixir-nebulex/nebulex_streams/compare/52c4174d9835e0865e3518143ec9c9d2beb122af...v0.1.0)
+
+### Features
+
+- **Real-time Event Streaming**: Processes can subscribe to and react to cache
+  entry events (inserted, updated, deleted, expired, evicted) as they happen.
+- **Partitioned Streams**: Events can be divided into multiple independent
+  sub-streams for parallel processing and scalability.
+- **Event Filtering**: Subscribers can filter to specific event types to reduce
+  message overhead.
+- **Distributed by Design**: Built on Phoenix.PubSub for seamless cluster-wide
+  event distribution.
+- **Automatic Cache Invalidation**: Built-in `Nebulex.Streams.Invalidator`
+  module for automatic entry removal when changes occur on other nodes.
+- **Telemetry Integration**: Comprehensive observability with telemetry events
+  for monitoring stream and invalidation behavior.
+- **Dynamic Cache Support**: Works with both statically-defined and
+  dynamically-created caches.
+- **Custom Partition Routing**: Support for custom hash functions to route
+  events to specific partitions based on business logic.
+
+### Enhancements
+
+- Comprehensive module documentation with examples and best practices.
+- Detailed option documentation with inline examples.
+- Troubleshooting guides and performance tuning recommendations.
+- Support for event scopes (`:remote`, `:local`, `:all`) in invalidator for
+  flexible consistency strategies.

CHANGELOG.md

@@ -18,6 +18,8 @@ applications and real-time monitoring.
 - 🎯 **Event Filtering** - Subscribe to specific event types.
 - 🌐 **Distributed** - Built on Phoenix.PubSub for cluster-wide events.
 - 📊 **Telemetry** - Comprehensive observability with telemetry events.
+- 🔄 **Built-in Invalidation** - Automatic cache invalidation for distributed
+  consistency.
 
 ## Installation
 
@@ -287,6 +289,27 @@ Nebulex Streams supports dynamic caches:
 MyApp.Cache.subscribe(:my_dynamic_cache, [])
 ```
 
+## Automatic Cache Invalidation
+
+For distributed cache scenarios, Nebulex Streams includes a built-in
+[`Nebulex.Streams.Invalidator`](https://hexdocs.pm/nebulex_streams/Nebulex.Streams.Invalidator.html)
+that automatically removes stale entries when they change on other nodes. This
+implements a "fail-safe" approach to cache consistency.
+
+```elixir
+# Add to your supervision tree after the stream
+children = [
+  MyApp.Cache,
+  {Nebulex.Streams, cache: MyApp.Cache},
+  {Nebulex.Streams.Invalidator, cache: MyApp.Cache}  # Watch for changes
+]
+
+Supervisor.start_link(children, strategy: :rest_for_one)
+```
+
+For detailed options and patterns, see the
+[Invalidator documentation](https://hexdocs.pm/nebulex_streams/Nebulex.Streams.Invalidator.html).
+
 ## Contributing
 
 Contributions to Nebulex are very welcome and appreciated!