[ENG-4159] docs: quota optimization docs

src/customer-guides/salesforce.mdx

@@ -86,6 +86,7 @@ Pick one way to connect, then grant the permissions below.
 
 - **API Enabled**
 - If the integration includes real-time Subscribe Actions, also enable the [Subscribe Action permissions](#subscribe-action-permissions)
+- If you want to enable quota optimization for this installation, also enable the [Quota optimization permissions](#quota-optimization-permissions)
 - For Connected Apps only, also enable one of:
   - **Use Any API Client** (shown if your org has [API Access Control](https://help.salesforce.com/s/articleView?id=xcloud.security_api_access_control_about.htm&type=5) enabled)
   - **Approve Uninstalled Connected Apps** (if you do not see **Use Any API Client**)
@@ -280,3 +281,12 @@ Salesforce auto-enables these dependent permissions when you enable the ones abo
 - **Manage Custom Permissions** — create and manage dedicated event channels and channel memberships for the installation
 
 Enable these on the profile (Option A, step 1) or permission set (Option B, step 4) you configured above.
+
+## Quota optimization permissions
+
+Quota optimization also requires these additional permissions in addition to [Subscribe Action permissions](#subscribe-action-permissions). 
+
+- **Author Apex** — required to write and deploy an Apex trigger used by the optimization
+- **Manage Profiles and Permission Sets** and **Assign Permission Sets** — required so the integration can create a dedicated permission set to manage field access and field-level security for a custom checkbox field
+
+Enable these on the profile (Option A, step 1) or permission set (Option B, step 4) you configured above.

src/provider-guides/salesforce.mdx

@@ -15,7 +15,7 @@ This connector has two modules, with CRM as the default.
 The **CRM** module supports:
 - [Proxy Actions](/proxy-actions), using the base URL `https://{{.workspace}}.my.salesforce.com`.
 - [Read Actions](/read-actions), including full historic backfill, incremental read, and filters.
-- [Subscribe Actions](/subscribe-actions).
+- [Subscribe Actions](/subscribe-actions). See [Quota optimization for Subscribe Actions](#quota-optimization-for-subscribe-actions) to reduce CDC / platform event quota usage.
 - [Write Actions](/write-actions), including Bulk Write and Delete.
 
 The **Account Engagement** module supports:
@@ -431,6 +431,92 @@ To start integrating with Salesforce:
    - If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
    - If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.
 
+## Quota optimization for Subscribe Actions
+
+Quota optimization is an opt-in feature for [Subscribe actions](/subscribe-actions). It limits update events to the fields you care about, so irrelevant changes are filtered out at the source and do not count against Salesforce's shared [daily delivery allocation for Change Data Capture (CDC) and platform events](https://developer.salesforce.com/docs/atlas.en-us.change_data_capture.meta/change_data_capture/cdc_allocations.htm) (`DailyDeliveredPlatformEvents`) — a rolling 24-hour limit on how many events can be delivered to API subscribers.
+
+### How it works
+
+Salesforce CDC does not natively support fine-grained field-level filtering in a way that avoids using that allocation. Ampersand adds an optimization layer on each opted-in object:
+
+1. A custom checkbox field is created on the object.
+2. An Apex trigger is created that sets this field when a watched field changes.
+3. CDC is configured to emit events only when this checkbox field is `true`.
+
+As a result, update events are delivered only when meaningful changes occur.
+
+### What is created in Salesforce
+
+When quota optimization is enabled for an object, Ampersand creates the following artifacts in the customer's Salesforce org:
+
+**Custom checkbox field**
+
+- API name: `<appName>_cdc_event_flag__c`
+- `<appName>` is your Ampersand [project](/terminology#project) `appName`, sanitized for Salesforce: lowercased, special characters removed, spaces and hyphens replaced with underscores.
+
+![Custom checkbox field in Salesforce Object Manager Fields & Relationships](/images/account_checkbox.png)
+
+**Apex trigger**
+
+- Name format: `CDC_<ObjectName>` (for example, `CDC_Account`)
+
+![Apex triggers in Salesforce Setup](/images/apex_triggers.png)
+
+You can verify these artifacts in Salesforce Setup after the installation (or installation update) completes. Subscription setup usually takes 1–2 minutes, and sometimes up to 10 minutes.
+
+### Permissions
+
+The installing user needs these permissions beyond the usual [Subscribe Action permissions](/customer-guides/salesforce#subscribe-action-permissions):
+
+- **Author Apex** — so Ampersand can write and deploy the Apex trigger
+- **Manage Profiles and Permission Sets** and **Assign Permission Sets** — so Ampersand can create a dedicated permission set for checkbox field access and field-level security
+
+Share the [Quota optimization permissions](/customer-guides/salesforce#quota-optimization-permissions) section of the Salesforce customer guide so they can grant these before installing or updating.
+
+### Configuration
+
+Enable quota optimization per object in the installation config when you [create](/reference/installation/create-a-new-installation) or [update](/reference/installation/update-an-installation) an installation. Set `providerOptions.quotaOptimization.enabled` to `true` on the subscribe object.
+
+Requirements:
+
+- A [Read action](/read-actions) must be defined for the same object, with `inheritFieldsAndMapping: true` (required for Salesforce subscribe)
+- `updateEvent.enabled` must be `always`
+- `updateEvent.requiredWatchFields` must be non-empty and include every field you want to watch. With quota optimization enabled, only changes to these fields produce Subscribe update events; changes to other fields are filtered out at the source and are not delivered.
+- Do not use `updateEvent.watchFieldsAuto: all` with quota optimization
+
+Here is a sample request body for the [Create Installation API](/reference/installation/create-a-new-installation):
+
+```Javascript
+{
+  "groupRef": "customer-group-ref",
+  "connectionId": "connection-id",
+  "config": {
+    "revisionId": "revision-id",
+    "content": {
+      "provider": "salesforce",
+      "subscribe": {
+        "objects": {
+          "account": {
+            "objectName": "account",
+            "destination": "accountWebhook",
+            "inheritFieldsAndMappings": true,
+            "updateEvent": {
+              "enabled": "always",
+              "requiredWatchFields": ["name", "billingcity", "phone"]
+            },
+            "providerOptions": {
+              "quotaOptimization": {
+                "enabled": true
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
 ## Customer guide
 
 The [Salesforce customer guide](/customer-guides/salesforce) is a guide that can be shared with your customers to help them be successful in using your integration.

src/subscribe-actions.mdx

@@ -78,6 +78,12 @@ integrations:
 
 For an example of a webhook message delivered according to the above `amp.yaml`, please see [Subscribe action webhooks](/destinations/webhooks#subscribe-action-webhooks).
 
+### Quota optimization
+
+Quota optimization reduces API quota consumption for Subscribe update events by filtering irrelevant change events at the source, so only updates that affect watched fields are delivered. It is opt-in and is not enabled by default.
+
+Currently supported for Salesforce. See [Quota optimization for Subscribe Actions](/provider-guides/salesforce#quota-optimization-for-subscribe-actions) in the Salesforce provider guide for more information.
+
 ### Association changes
 
 In HubSpot, association changes do not trigger update events, you must subscribe to them specifically using `associationChangeEvent`. On the other hand, in Salesforce, you can subscribe to fields that refer to associations (e.g. You can subscribe to update events on the `accountid` field of contacts).