docs(audiences): expand field mapping intent best practice to cover SFDC import sync path

[george-dilthey]

What changed

Expanded the "Check your field mapping intent before hitting Start Run" best practice in docs/audiences.md from a one-sentence note into a three-bullet decision guide. The new third bullet explains that when a bulk enrichment writes data back to Salesforce and those Salesforce fields are already mapped in the import field mapping, bulk-enrich field mapping is not required — updated values will appear in the Audience record on the next import sync automatically. If the fields are not in the import field mapping, the user must either enable bulk-enrich field mapping or add those fields to the import field mapping.

Why

An Amplitude Enterprise customer (Matt Kahan) asked: "Is there any reason I should be including field mapping to audiences on if we're using this enrichment to update the SFDC records that feed into the audiences anyways? Currently have it turned off." The existing best practice only covered two scenarios (write-directly-to-Audiences and action-only runs) and was silent on this common third pattern — enrichment writes to SFDC, SFDC import sync brings it back into Audiences. A human support agent (Ariana) had to explain the nuance; the answer belongs in the doc so Fin can surface it next time.

Source link(s)

• Intercom conversation: https://app.intercom.com/a/inbox/w28k1kwz/inbox/conversation/215475590395747
• Slack trigger thread: https://clay-hq.slack.com/archives/C07532PH8BT/p1787344978559599

Verifier sub-agent returned PASS on all four behavioral claims with code evidence:

• Import sync processes only fields in importSync.fieldMapping: clay-base/services/audiences/src/utils/field-mapping-helpers.ts:105-146
• Mapped field appears on Audience record on next sync with no bulk-enrich field mapping needed: clay-base/services/audiences/src/materialization/services/big-source-import-handler.ts:49-55
• "Field mapping is off" warning text confirmed: clay-base/apps/frontend/src/components/SettingsEditor/SendToAudiences/SendToAudiencesSettingsEditor.tsx:217-220
• Slack context: no discrepancies or upcoming changes found.

Uncertainties

None — all behavioral claims verified PASS against code.

Related observations

Several other open PRs touch docs/audiences.md but none cover the import-field-mapping vs. bulk-enrich-field-mapping decision point: PRs #2321, #2320, #2317, #2312, #2311, #2305, #2303, #2298, #2295, #2291, #2288, #2280, #2277, #2272, #2261, #2251, #2245, #2232, #2231, #2228, #2227, #2225, #2224. Each was reviewed for overlap; none address this scenario. Reviewers merging those PRs should verify no merge conflicts arise with the best-practice section near the end of the file.

Closes DOC-2078

[linear-code]

DOC-2078