docs(audiences): document CSV import replacement workflow and source listing limitation

[george-dilthey]

What changed

Added two pieces of content to docs/audiences.md:

1. In the "Importing from CSV" section — appended a note explaining how to replace a CSV import with corrected data (archive old records first, then re-import), and a note that CSV source entries cannot be removed from the Sources tab.

2. New FAQ: "How do I replace a CSV import with updated data?" — step-by-step instructions for archiving records by Origin source filter and re-importing a corrected CSV.

Why

Intercom conversation #215475096866466 (subject: "Removing data from audience"): a customer asked how to delete a CSV source from Audiences because their accounts had changed and they needed to import corrected data. Fin did not respond; the ticket went straight to a human agent (Peter Johnston). Peter's reply was the correct authoritative answer — the gap was that the docs had no guidance on this workflow.

The existing "Importing from CSV" section told users to "repeat the import process with an updated file" but gave no guidance on archiving the old records first, and didn't explain the limitation on source deletion.

Source link(s)

• Intercom conversation: https://app.intercom.com/a/inbox/_/inbox/conversation/215475096866466
• Human agent reply (Peter Johnston): confirmed users cannot self-serve delete CSV sources and provided the archive-then-reimport workaround
• PSS channel thread: https://clay-hq.slack.com/archives/C0B8PRBB6ET/p1784132196016249 — Peter asked PSS bot which confirmed the same workflow (high confidence)
• #team-audiences thread (Mark Larson, product team): https://clay-hq.slack.com/archives/C08B9DAQQP3/p1784279911960209 — confirmed "Origin source / = / csv name" filter approach and that the source listing cannot be deleted self-serve
• Verifier sub-agent verdicts:
  • PASS — CSV sources cannot be disconnected/removed from Sources tab (clay-base/apps/frontend/src/components/Audiences/AudiencesSettings/AudiencesWorkspaceSettingsPage/SyncViews/Sources/AudiencesSourcesActionsCell.tsx — SourceRowType.Local returns empty action array; clay-base/libs/shared/src/audiences/sync-source-types.ts:68–73 — CSV is INTERNAL_AUDIENCE_IMPORT_SOURCE_TYPES, not external)
  • PASS — "Deleted in source" label confirmed (clay-base/libs/shared/src/audiences/import-types.ts:15)
  • PASS — Archive + re-import workflow confirmed (clay-base/apps/frontend/src/state/Audiences/useAudienceSegmentDropdownOptions.tsx:219,237; clay-base/apps/api/v3/audiences/endpoints/audiences-imports.endpoints.ts:338)
  • "Origin source" filter label confirmed: clay-base/libs/shared/src/filter-builder/filterRuleDefinitions/audiencesRuleFieldDefinitions.ts:11

Uncertainties

None. All claims verified against code with PASS verdicts and corroborated by a product team Slack thread from today.

Related observations

• There are 12 open PRs on audiences.md (PRs docs(audiences): add Databricks as beta import source #1485, docs(audiences): add field-filter warning to Snowflake and BigQuery import steps #1507, docs(audiences): document Salesforce custom object export limitation and workaround #1528, docs(audiences): add FAQ clarifying dedup scope — Audiences only, not Clay tables #1547, docs(audiences): add CSV export workaround via Add to workbook #1550, docs(audiences): document nested sub-field mapping in bulk enrichments #1558, docs(audiences): document Intelligence tab on company records (beta) #1569, docs(audiences): add errored-row run-condition fix, delete-row note, and field-deletion FAQ #1582, docs(audiences): add read-only Salesforce field types and cross-object enrichment FAQ #1585, docs(audiences): document archived record behavior on source re-sync #1587, docs(audiences): document signal detection-layer model and Data Hub vs. table scope #1605, docs(audiences): add Export sync toggle prerequisite for Salesforce write-back #1615). None of them address the CSV import replacement workflow or the CSV source listing limitation — reviewed each diff. This change is materially distinct.
• The doc already documents "Deleted in source" in the Salesforce section; the CSV section doesn't need this since CSV is one-time (no ongoing sync to mark records deleted-from-source).
• A #dust-support thread from today (2026-07-17) showed Clay's internal Dust bot guessing incorrectly about CSV source deletion — corroborating the doc gap.

Closes DOC-1220

[linear-code]

DOC-1220