Add cache tags to docs

docs/docs/cache.md

@@ -205,7 +205,125 @@ Cache::flush();
 Flushing the cache does not respect your configured cache "prefix" and will remove all entries from the cache. Consider this carefully when clearing a cache which is shared by other applications.
 :::
 
-### Building Cache Stacks
+## Cache Tags
+
+Cache tags allow you to tag related items in the cache and then flush all cached values that have been assigned a given tag. In Hypervel, only the `redis` driver supports cache tags.
+
+### Tag Modes
+
+Hypervel supports two tag modes that determine how tags behave. Configure the mode in your `config/cache.php`:
+
+```php
+'redis' => [
+    'driver' => 'redis',
+    'connection' => 'default',
+    'tag_mode' => env('REDIS_CACHE_TAG_MODE', 'all'),
+],
+```
+
+| Mode | Requirements | Description |
+|------|--------------|-------------|
+| `all` (default) | Any Redis version | Tags define storage scope. Items require the same tags for retrieval and flushing. |
+| `any` | Redis 8.0+ or Valkey 9.0+ | Tags are for grouping items for invalidation. Flush items by any matching tag. |
+
+### All Mode (Default)
+
+All mode matches Laravel's cache tag behavior. When storing items with tags, the tags define the storage scope - you must provide the same tags to retrieve or flush the items.
+
+#### Storing Tagged Cache Items
+
+```php
+Cache::tags(['people', 'artists'])->put('John', $john, $seconds);
+Cache::tags(['people', 'authors'])->put('Anne', $anne, $seconds);
+```
+
+#### Accessing Tagged Cache Items
+
+Items stored with tags can only be retrieved by providing the same tags:
+
+```php
+$john = Cache::tags(['people', 'artists'])->get('John');
+$anne = Cache::tags(['people', 'authors'])->get('Anne');
+```
+
+#### Removing Tagged Cache Items
+
+To flush items, you must provide all the tags they were stored with:
+
+```php
+// Removes Anne (stored with 'people' and 'authors')
+Cache::tags(['people', 'authors'])->flush();
+
+// Removes John (stored with 'people' and 'artists')
+Cache::tags(['people', 'artists'])->flush();
+
+// Does nothing - no items were stored with only 'people'
+Cache::tags(['people'])->flush();
+```
+
+### Any Mode
+
+Any mode provides a "tag by many, flush by any" pattern. Items can be tagged with multiple categories, then flushed by any single tag. Items are retrieved directly without specifying tags.
+
+::: warning
+Any mode requires Redis 8.0+ (or Valkey 9.0+) and PhpRedis 6.3.0+. These are hard requirements - any mode will not function on older versions. Run `php artisan cache:redis-doctor` to verify your environment meets these requirements.
+:::
+
+#### Storing Tagged Cache Items
+
+```php
+Cache::tags(['posts', 'user:123'])->put('post-1', $post, $seconds);
+Cache::tags(['posts', 'featured'])->put('post-2', $featured, $seconds);
+```
+
+#### Accessing Tagged Cache Items
+
+In any mode, retrieve items directly without tags:
+
+```php
+$post = Cache::get('post-1');
+$featured = Cache::get('post-2');
+```
+
+::: warning
+Attempting to retrieve items via tags in any mode will throw an exception. Tags are for storing and flushing only.
+:::
+
+#### Removing Tagged Cache Items
+
+Flushing removes all items that have any of the specified tags:
+
+```php
+// Removes all items tagged with 'posts' (both post-1 and post-2)
+Cache::tags(['posts'])->flush();
+
+// Removes all items tagged with 'user:123' (only post-1)
+Cache::tags(['user:123'])->flush();
+
+// Removes items tagged with 'posts' OR 'featured' (both)
+Cache::tags(['posts', 'featured'])->flush();
+```
+
+### Pruning Stale Cache Tags
+
+::: danger
+You must schedule the prune command to prevent memory leaks. When cached items expire, their tag references remain and accumulate over time.
+:::
+
+Add the following to your scheduler:
+
+```php
+$schedule->command('cache:prune-redis-stale-tags')->hourly();
+```
+
+You may also run the command manually:
+
+```bash
+php artisan cache:prune-redis-stale-tags
+php artisan cache:prune-redis-stale-tags my-store
+```
+
+## Building Cache Stacks
 
 Hypervel provides multi-tier caching architecture. The `stack` driver allows you to combine multiple cache layers for ultra performance. To illustrate how to use cache stacks, let's take a look at an example configuration that you might see in a production application: