[ENG-3818] docs: document read field filters in manifest reference

src/manifest-reference.mdx

@@ -209,6 +209,9 @@ Each object in the `objects` array defines a specific data type to read from the
 | `mapToName` | String | No | An optional name mapping for this object. Used to standardize object names across different providers. See [Object and Field Mapping](/object-and-field-mapping) for details. |
 | `mapToDisplayName` | String | No | An optional display name mapping for this object. Used for UI display. |
 
+These fields control **which fields** are read. To control **which records** are read, use `fieldFilters`, which is set per-installation in the installation config rather than in `amp.yaml`.
+> Learn more in [Field filters](#field-filters).
+
 <Note>
 When configuring fields for a read object, keep these points in mind:
 
@@ -312,9 +315,16 @@ Backfill Considerations
 
 - Setting `fullHistory: true` may result in longer initial sync times, especially for large datasets.
 - Some providers may have API rate limits that affect backfill performance.
+- In the installation config, the `backfill` object accepts one additional key, `fieldFilters`, which restricts the records read during backfill. It is not available in `amp.yaml`. See [Field filters](#field-filters).
 - See [Read Actions backfill behavior](/read-actions#backfill-behavior) for detailed implementation guidance.
 </Note>
 
+### Field filters
+
+Field filters restrict **which records** a read action returns, by matching against field values. Only matching records are read and delivered to your destination.
+
+Unlike every other field on this page, `fieldFilters` is **not part of the manifest schema** — it cannot be set in `amp.yaml`. It is set per-installation in the installation config, when creating or updating an installation via the [REST API](/reference/installation/create-a-new-installation) or Headless UI's [createInstallation method](/headless#create-update-and-delete-installations). See the linked documentation for more information.
+
 ### Field
 
 In [Read Actions](#read-definition), fields can be configured in two main ways - either using a simple `fieldName` reference or using a mapped field approach (`mapToName`, `mapToDisplayName`, `prompt`, `default`). This flexibility allows for both direct field references and more sophisticated field mapping options.

src/read-actions.mdx

@@ -202,6 +202,34 @@ If you want different filter behavior for backfill vs. incremental reads, you ca
 
 In this example, the backfill will only return contacts whose `firstname` equals "Brian", while subsequent incremental reads will only return contacts whose `status` equals "active".
 
+### Filter field names
+
+The `fieldName` of a filter must be the field's name in the provider's API, and it is case-sensitive.
+
+<Warning>
+Read filters do **not** resolve [object and field mappings](/object-and-field-mapping). A `mapToName` from your `amp.yaml`, or a mapping your customer selected during installation, is not translated to the underlying provider field. This differs from [search actions](/search-actions#execute-a-search), which do accept mapped field names.
+</Warning>
+
+For example, if your manifest maps the provider field `mobilephone` to `phone`:
+
+```yaml
+requiredFields:
+  - fieldName: mobilephone
+    mapToName: phone
+```
+
+then a filter on that field must still reference `mobilephone`:
+
+```json
+// Correct — the provider's field name
+{ "fieldName": "mobilephone", "operator": "eq", "value": "1234567890" }
+
+// Incorrect — mapToName is not resolved, so the read will fail or return no records
+{ "fieldName": "phone", "operator": "eq", "value": "1234567890" }
+```
+
+The field you filter on does not have to be one of the object's `selectedFields`. You can filter on a field that you don't read.
+
 ### Valid filter values
 
 The `value` field of the filter accepts strings, booleans, and numbers: