Add cache stampede protection documentation

Document the recommended pattern for preventing cache stampedes using
CacheLockProvider with the existing cache-aside pattern in both the
caching guide and the Foundatio agent skill gotchas.

Author: niemyjski

.agents/skills/foundatio/SKILL.md

@@ -302,6 +302,7 @@ public class OrderServiceTests : TestLoggerBase
 - **Dispose streams and locks**: `ILock` is `IAsyncDisposable` -- use `await using`. Streams from `GetFileStreamAsync` are `IDisposable` -- use `using var`.
 - **Cache TTL floor**: Expiration values below 5ms are treated as already-expired and the key is silently removed. If you compute TTL dynamically (e.g., `expiresAt - now`), guard against near-zero values.
 - **Cache `GetAsync` returns `CacheValue<T>`**: Check `result.HasValue` before accessing `result.Value`. A missing key returns `HasValue = false`, not an exception.
+- **Cache stampede (thundering herd)**: The cache-aside pattern (`Get` -> miss -> load -> `Set`) is vulnerable to stampedes when a popular key expires and many callers regenerate simultaneously. Use `CacheLockProvider` to serialize regeneration: acquire a lock keyed on the cache key, double-check the cache after acquiring, and only then call the backing store. See the [Cache Stampede Protection](https://foundatio.readthedocs.io/guide/caching.html#cache-stampede-protection) docs for the full pattern.
 - **Queue auto-complete**: `QueueJobBase<T>` auto-completes entries based on `JobResult` by default. Set `AutoComplete = false` only when you need manual `CompleteAsync()`/`AbandonAsync()` control. Manual `DequeueAsync` does NOT auto-complete.
 - **JobWithLockBase vs manual locking**: Use `JobWithLockBase` when the entire run must be single-instance (leader election). Use manual `ILockProvider.AcquireAsync` inside `JobBase` for finer-grained locking within a job.
 - **JobContext.RenewLockAsync**: Call in long-running jobs (both `JobBase` and `QueueJobBase`) to prevent lock expiration mid-processing.

docs/guide/caching.md

@@ -579,6 +579,63 @@ public async Task<User> GetUserAsync(int userId)
 }
 ```
 
+### Cache Stampede Protection
+
+The cache-aside pattern above is vulnerable to **cache stampedes** (also called the thundering herd problem). When a popular key expires, many concurrent requests all see a cache miss simultaneously and each independently loads the same data from the backing store. For an expensive query that takes two seconds to run, 50 concurrent callers means 50 identical database queries instead of one.
+
+Use [`CacheLockProvider`](/guide/locks) to serialize cache regeneration so only one caller loads the data while others wait:
+
+```csharp
+public class ProductService
+{
+    private readonly ICacheClient _cache;
+    private readonly ILockProvider _locker;
+
+    public ProductService(ICacheClient cache, ILockProvider locker)
+    {
+        _cache = cache;
+        _locker = locker;
+    }
+
+    public async Task<Product?> GetProductAsync(int productId, CancellationToken ct)
+    {
+        var cacheKey = $"product:{productId}";
+
+        var cached = await _cache.GetAsync<Product>(cacheKey);
+        if (cached.HasValue)
+            return cached.Value;
+
+        // Only one caller regenerates; others wait for the lock then re-check cache.
+        await using var lck = await _locker.AcquireAsync(
+            $"cache-load:{cacheKey}",
+            timeUntilExpires: TimeSpan.FromSeconds(30),
+            cancellationToken: ct);
+
+        if (lck is null)
+            return null; // Could not acquire -- caller decides how to handle
+
+        // Double-check: another caller may have populated cache while we waited.
+        cached = await _cache.GetAsync<Product>(cacheKey);
+        if (cached.HasValue)
+            return cached.Value;
+
+        var product = await _database.GetProductAsync(productId);
+        await _cache.SetAsync(cacheKey, product, TimeSpan.FromMinutes(30));
+        return product;
+    }
+}
+```
+
+The key points of this pattern:
+
+1. **Lock on the cache key.** Use a lock name derived from the cache key (e.g., `cache-load:product:42`) so different keys are loaded concurrently while the same key is serialized.
+2. **Double-check after acquiring.** Another caller may have populated the cache while you were waiting for the lock. Always re-read before loading from the backing store.
+3. **Lock expiration as a safety net.** Set `timeUntilExpires` to a value longer than the expected load time. If the loader crashes, the lock auto-expires and the next caller retries.
+
+::: tip CacheLockProvider + IMessageBus
+When `CacheLockProvider` is configured with an `IMessageBus`, waiting callers are notified instantly via pub/sub when the lock is released. Without a message bus, lock release falls back to polling. For stampede protection where multiple callers are blocked on the same lock, the message bus significantly reduces wait time.
+:::
+
 ### Atomic Operations
 
 Use conditional operations for race-safe updates: