docs(audiences): document field-level write rules for Salesforce export

[george-dilthey]

What changed

Added a Field-level write rules table to docs/audiences.md in the "Writing back to your CRM" section. The table defines the three export write rules for Salesforce field mappings — Never write (default), Always write, and Write if empty — explains what each does, how to change them (click the pencil icon), and calls out that "Never write" is the default for all newly added field mappings.

Why

Intercom conversation #215475130065193 (Saviynt / Gabriel Griffith): Customer had mapped fields to Salesforce on the Accounts object and was confused about why data wasn't syncing. A human admin (Peter Johnston) resolved it by explaining that the Export sync toggle must be enabled as the master switch, and that the first export runs within the next 24-hour window. The existing FAQ ("I've mapped fields to Salesforce but the data isn't syncing — why?") already covers the master toggle correctly. However, nowhere in the doc are the three field-level write rules defined — they are referenced by name but never explained. A customer who maps new fields but doesn't know "Never write" is the default would not know to change the rule, and the doc currently gives no guidance on this.

Why this is materially new vs. PR #1615: PR #1615 (also open on this file) mentions the three rule names in a troubleshooting FAQ ("Field-level write rules (Always write, Write if empty, Never write) control which fields get pushed...") but does not define them, does not explain that "Never write" is the default, and does not show the behavioral table. This PR adds that explanatory content to the main setup section.

Source link(s)

• Intercom conversation: https://app.intercom.com/a/inbox/w28k1kwz/inbox/conversation/215475130065193
• Write rules enum (PASS — three rules exist as code): /workspace/clay-base/libs/api-contract/src/audiences/lib/import-types.ts:38-42 — MappingRule.AlwaysWrite = 'ALWAYS_WRITE', MappingRule.WriteIfEmpty = 'WRITE_IF_EMPTY', MappingRule.NeverWrite = 'NEVER_WRITE'
• Never write is the default (PASS): /workspace/clay-base/apps/frontend/src/components/Audiences/utils/AudienceMappingHelpers.ts:20 — export const DEFAULT_MAPPING_RULE = MappingRule.NeverWrite;
• UI display names match (PASS): same file lines 22–31 — getDisplayTextForMappingRule returns 'Always write', 'Write if empty', 'Never write' for each enum value
• Slack support thread confirming write rules flow: https://clay-hq.slack.com/archives/C08RHUMFP6Z/p1773072006772409

Uncertainties

None — all behavioral claims (write rules definition, Never write as default, UI display names) verified PASS by verifier sub-agent and direct code inspection against the above file:line citations.

Related observations

• PR docs(audiences): add Export sync toggle prerequisite for Salesforce write-back #1615 (open) also touches docs/audiences.md and mentions write rules by name in a troubleshooting FAQ, but does not define them or note the default. Reviewer should reconcile these two additions at merge time to avoid redundancy (e.g. the write rules table from this PR could become the canonical reference that the FAQ in docs(audiences): add Export sync toggle prerequisite for Salesforce write-back #1615 links to).
• PRs docs(audiences): document signal detection-layer model and Data Hub vs. table scope #1605, docs(audiences): document archived record behavior on source re-sync #1587, docs(audiences): add read-only Salesforce field types and cross-object enrichment FAQ #1585, docs(audiences): add errored-row run-condition fix, delete-row note, and field-deletion FAQ #1582, docs(audiences): document Intelligence tab on company records (beta) #1569, docs(audiences): document nested sub-field mapping in bulk enrichments #1558, docs(audiences): add CSV export workaround via Add to workbook #1550, docs(audiences): add FAQ clarifying dedup scope — Audiences only, not Clay tables #1547, docs(audiences): document Salesforce custom object export limitation and workaround #1528, docs(audiences): add field-filter warning to Snowflake and BigQuery import steps #1507, docs(audiences): add Databricks as beta import source #1485 also touch this file but cover unrelated topics (signals, archiving, Databricks import, etc.).

Closes DOC-1224

[linear-code]

DOC-1224