docs(cache): say what ShardKeyEnabled changes besides co-location

CHANGELOG.md

@@ -373,7 +373,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
   `app:s:{authz_{orgid}_groups_1}` — Redis hashes from the first `{` to the next `}`, so the tag was
   the accidental `authz_{orgid` rather than the org the caller asked for. A key with a valid hash tag
   (non-empty content between the first `{` and the next `}`) is now prefixed and left as-is, so the
-  caller's tag picks the slot and multi-key commands land where the caller intended. Non-empty keys with no
+  caller's tag picks the slot and multi-key commands land where the caller intended, given a brace-free prefix. Non-empty keys with no
   braces are wrapped exactly as before; keys whose braces form no valid tag were wrapped by this change too, and
   are refused outright by *A cache key that cannot carry a hash tag is refused rather than wrapped* later in this
   release. This relocates existing entries only for apps
@@ -382,8 +382,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 ### Deprecated
 
 - **`CacheOptions.ShardKeyEnabled`.** It wraps a brace-free cache key in a `{...}` hash tag so the slot follows
-  the key rather than `AppShortName` and the differentiator. That changes *which* keys share a slot and nothing
-  else: the tag becomes the whole key, unique per key just as the untagged key was, so it spreads no better, and
+  the key rather than `AppShortName` and the differentiator. That changes *which* keys share a slot, not how
+  evenly they spread: the tag becomes the whole key, unique per key just as the untagged key was, so it spreads no better, and
   it cannot make a multi-key batch land on one node. A key that already carries a valid `{tag}` is rendered
   identically on either setting, so the flag makes no difference to batching in either direction; a key whose
   braces form no valid tag is refused outright when it is set. What it does do is co-locate one key across every

docs/reference/settings.md

@@ -20,7 +20,7 @@ Every binding-visible property on every shipped options class, with shipped defa
 | `Enabled` | `bool` | `true` | App-wide | Master on/off switch for the caching subsystem. |
 | `TelemetryEnabled` | `bool` | `true` | App-wide | Gates the `ICachingTelemetryProvider` seam; set to `false` to silence all cache metrics. |
 | `BroadcastEnabled` | `bool` | `true` | App-wide | Gates the `ITopicFactory` wiring; set to `false` to disable all invalidation broadcasts. |
-| `ShardKeyEnabled` | `bool` | `false` | App-wide | **Deprecated.** Wraps a brace-free cache key in a `{...}` hash tag so the key alone picks its slot. That changes which keys co-locate and nothing more: the tag is the whole key, so it spreads no better and cannot make a multi-key batch single-slot. A key that already carries a valid tag renders the same either way; one whose braces form no valid tag is refused. Keep braces out of `AppShortName`, `Separator` and the differentiator too, since braces there change which span Redis hashes. Flipping the flag rewrites every brace-free key, so leave it as your deployment has it. To batch across keys on a cluster, give the keys a shared hash tag yourself. |
+| `ShardKeyEnabled` | `bool` | `false` | App-wide | **Deprecated.** Wraps a brace-free cache key in a `{...}` hash tag so the key alone picks its slot. That changes which keys co-locate, not how evenly they spread: the tag is the whole key, so it spreads no better and cannot make a multi-key batch single-slot. A key that already carries a valid tag renders the same either way; one whose braces form no valid tag is refused while the flag is on. Keep braces out of `KeyPrefix`, `AppShortName`, `Separator` and the differentiator too, since braces there change which span Redis hashes. Flipping the flag rewrites every brace-free key, so leave it as your deployment has it. To batch across keys on a cluster, give the keys a shared hash tag yourself. |
 | `AuditEnabled` | `bool` | `true` | App-wide | Log writes whose serialized size exceeds `LargeValueThreshold` bytes. |
 | `DefaultCache` | `string` | `"InMemoryRedis"` | App-wide | Provider name resolved when no explicit provider is requested; values: `InMemory`, `Redis`, `InMemoryRedis`. |
 | `DefaultTopic` | `string` | `"RedisStreams"` | App-wide | Topic provider used when no explicit topic is requested; values: `RedisStreams`, `RedisPubSub`. |

samples/UiPath.Caching.Sample/appsettings.all.json

@@ -9,7 +9,7 @@
     "TelemetryEnabled": true,
     // BroadcastEnabled: gate the ITopicFactory wiring
     "BroadcastEnabled": true,
-    // ShardKeyEnabled: deprecated; changes which keys co-locate, nothing more
+    // ShardKeyEnabled: deprecated; changes which keys co-locate, not how well they spread
     "ShardKeyEnabled": false,
     // AuditEnabled: log writes above LargeValueThreshold
     "AuditEnabled": true,

src/UiPath.Caching.Abstractions/CacheOptions.cs

@@ -17,7 +17,7 @@ public class CacheOptions
     [SuppressMessage("Major Code Smell",
         "S1133:Deprecated code should be removed",
         Justification = "Still read, so removing it would relocate every brace-free key.")]
-    [Obsolete("Changes which keys co-locate, nothing more. Flipping it relocates every brace-free entry.")]
+    [Obsolete("Changes which keys co-locate, not how well they spread, and refuses a key whose braces form no valid tag. Flipping it relocates every brace-free entry.")]
     public bool ShardKeyEnabled { get; set; }
 
     public bool AuditEnabled { get; set; } = true;