Add integrated cache best practice rule

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "azure-cosmosdb",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Official Claude plugin for Azure Cosmos DB (NoSQL). Bundles skills for data modeling, partition key design, query optimization, SDK best practices, indexing, vector search, full-text search, global distribution, security, and more.",
   "author": {
     "name": "Azure Cosmos DB",

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "azure-cosmosdb",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Official Codex plugin for Azure Cosmos DB (NoSQL). Best practice skills for data modeling, queries, indexing, vector search, security, and more.",
   "author": {
     "name": "Azure Cosmos DB",

.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "azure-cosmosdb",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Official Cursor plugin for Azure Cosmos DB (NoSQL). Best practice skills for data modeling, queries, indexing, vector search, security, and more.",
   "author": {
     "name": "Azure Cosmos DB",

.kimi-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "azure-cosmosdb",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Official Kimi Code plugin for Azure Cosmos DB (NoSQL) with bundled skills and MCP access for data modeling, partition key design, query optimization, SDK best practices, indexing, vector search, full-text search, global distribution, and security.",
   "author": {
     "name": "Azure Cosmos DB",

apm.yml

@@ -1,5 +1,5 @@
 name: cosmosdb-agent-kit
-version: 1.2.0
+version: 1.2.1
 description: >-
   Azure Cosmos DB best practices and performance optimization skills for AI coding agents.
   Provides expert guidance on data modeling, partition key design, query optimization,

gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "azure-cosmosdb",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Official Gemini extension for Azure Cosmos DB (NoSQL). Provides best practice skills for data modeling, partition key design, query optimization, indexing, vector search, full-text search, global distribution, security, and more.",
   "skills": "./skills/"
 }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "cosmosdb-agent-kit",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Azure Cosmos DB best practices for AI coding agents",
   "keywords": [
     "cosmosdb",

plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "cosmosdb",
   "description": "Azure Cosmos DB best practices and performance optimization skills for AI coding agents. Provides expert guidance on data modeling, partition key design, query optimization, SDK usage, indexing, throughput, global distribution, vector search, and full-text search.",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "author": {
     "name": "Microsoft",
     "url": "https://github.com/AzureCosmosDB"

skills/cosmosdb-best-practices/SKILL.md

@@ -148,6 +148,7 @@ Reference these guidelines when:
 - [throughput-burst](rules/throughput-burst.md) - Understand burst capacity
 - [throughput-container-vs-database](rules/throughput-container-vs-database.md) - Choose allocation level wisely
 - [throughput-idle-container-review](rules/throughput-idle-container-review.md) - Review idle containers for lifecycle action
+- [throughput-integrated-cache](rules/throughput-integrated-cache.md) - Use integrated cache for read-heavy workloads with dedicated gateway
 - [throughput-ttl-stale-data](rules/throughput-ttl-stale-data.md) - Expire stale data with TTL before hitting storage limits
 - [throughput-serverless-migration](rules/throughput-serverless-migration.md) - Migrate a low-traffic provisioned account to serverless
 

skills/cosmosdb-best-practices/metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.2.0",
+  "version": "1.2.1",
   "organization": "CosmosDB Agent Kit",
   "date": "January 2026",
   "abstract": "Performance optimization and best practices guide for Azure Cosmos DB applications, ordered by impact. Contains rules for data modeling, partition key design, query optimization, SDK usage, indexing, throughput management, global distribution, monitoring, developer tooling, and vector search.",

skills/cosmosdb-best-practices/rules/sdk-connection-mode.md

@@ -7,7 +7,7 @@ tags: sdk, connection-mode, direct, performance
 
 ## Use Direct Connection Mode for Production
 
-Use Direct connection mode for production workloads. Gateway mode adds an extra network hop and is only needed for firewall-restricted environments.
+Use Direct connection mode for production workloads. Gateway mode adds an extra network hop and should generally be avoided unless the workload has a specific requirement for Gateway mode, such as firewall restrictions or Azure Cosmos DB integrated cache (via the dedicated gateway).
 
 **Incorrect (defaulting to Gateway mode):**
 
@@ -58,6 +58,7 @@ var gatewayClient = new CosmosClient(connectionString, new CosmosClientOptions
     // 1. Corporate firewall blocks TCP port range 10000-20000
     // 2. Running in Azure Functions Consumption plan (sometimes)
     // 3. Kubernetes with restrictive network policies
+    // 4. Using Azure Cosmos DB Integrated Cache, which requires the dedicated gateway endpoint/connection string
     ConnectionMode = ConnectionMode.Gateway
 });
 ```

skills/cosmosdb-best-practices/rules/throughput-integrated-cache.md

@@ -0,0 +1,63 @@
+---
+title: Use Integrated Cache for Read-Heavy Workloads with Dedicated Gateway
+impact: MEDIUM
+impactDescription: reduces RU consumption and latency for repeated reads
+tags: throughput, integrated-cache, dedicated-gateway, performance, cost, read-heavy
+---
+
+## Use Integrated Cache for Read-Heavy Workloads with Dedicated Gateway
+
+**Impact: MEDIUM (reduces RU consumption and latency for repeated reads)**
+
+For workloads that repeatedly read the same items or execute the same queries, Azure Cosmos DB's integrated cache can significantly reduce RU consumption and improve response latency. The integrated cache is available only when using a **dedicated gateway**. Cached point reads and queries can be served without contacting backend replicas until the configured cache staleness window expires.
+
+Use the `MaxIntegratedCacheStaleness` request option to control how stale cached results are allowed to be. Integrated cache is appropriate for read-heavy workloads where slightly stale data is acceptable, but it only applies to reads using **Session** or **Eventual** consistency.
+
+**Incorrect (point reads without integrated cache):**
+
+```csharp
+var client = new CosmosClient(connectionString);
+var container = client.GetContainer("database", "container");
+
+var response = await container.ReadItemAsync<Product>(
+    "product-1",
+    new PartitionKey("electronics"));
+```
+
+Every repeated request is sent to the backend, consuming RUs even when the data has not changed.
+
+**Correct (use dedicated gateway with integrated cache):**
+
+```csharp
+var client = new CosmosClient(
+    dedicatedGatewayConnectionString,
+    new CosmosClientOptions
+    {
+        ConnectionMode = ConnectionMode.Gateway
+    });
+
+var container = client.GetContainer("database", "container");
+
+var options = new ItemRequestOptions
+{
+    DedicatedGatewayRequestOptions = new DedicatedGatewayRequestOptions
+    {
+        MaxIntegratedCacheStaleness = TimeSpan.FromMinutes(5)
+    }
+};
+
+var response = await container.ReadItemAsync<Product>(
+    "product-1",
+    new PartitionKey("electronics"),
+    options);
+```
+
+Guidance:
+
+- Use integrated cache for read-heavy workloads with frequent repeated point reads or queries.
+- Connect through the **dedicated gateway** endpoint to enable integrated cache.
+- Configure `MaxIntegratedCacheStaleness` based on how much stale data your application can tolerate.
+- Use integrated cache only when **Eventual** or **Session** consistency satisfies application requirements.
+- Do not rely on integrated cache for workloads requiring **Strong**, **Bounded Staleness**, or **Consistent Prefix** consistency guarantees.
+
+Reference: <https://learn.microsoft.com/azure/cosmos-db/integrated-cache>