docs(audiences): add FAQ clarifying dedup scope — Audiences only, not Clay tables

[george-dilthey]

What changed

Added a new FAQ entry to docs/audiences.md — "Does Audiences Companies deduplication apply to my regular Clay tables?" — clarifying two things: (1) deduplication in Audiences is scoped to the Audiences data layer only and does not affect regular Clay tables; (2) domain-based deduplication within Audiences is not automatic — it requires an admin to explicitly configure deterministic matching at import setup time. Also directs users to Lookup in Audiences / Get Audiences Activity to query Audiences data from a table.

Why

A customer (james park) asked in Intercom: "If I uploading Company list in Audiences Companies, dedup function working in any table right away?" Fin couldn't resolve this and escalated. A human support agent replied with the correct scope (dedup stays in Audiences, not tables) but incorrectly stated that uploading to Audiences Companies auto-deduplicates by domain.

The existing docs/audiences.md covers entity resolution and import record matching (beta) in detail, but nowhere states explicitly that (a) Audiences dedup does NOT propagate to regular Clay tables, and (b) domain-based dedup is not automatic — it requires explicit admin configuration. Both gaps contributed to the escalation.

Source link(s)

• Intercom conversation: https://app.intercom.com/a/inbox/w28k1kwz/inbox/conversation/215475060233877
• Verifier run 1 (FAIL→corrected): The claim "auto-deduplicates based on domains" was FAIL. Code evidence: DEFAULT_IMPORT_ACCOUNT_ALIAS_PRECEDENCE at services/audiences/src/entity-resolution/hard-lookup.service.ts:48-52 = [ExternalSourceId, SourceLookUpField, ClayCompany] — CompanyDomain absent; domain aliases only set when fieldMatchingEntries is populated via admin configuration (upsert-account.ts:83-116). Confirmed by Slack threads from Grant Empey ("No we don't dedup here") and Ranveer Thind ("matching only happens if the admin configures that match settings across import sources").
• Verifier run 2 (PASS): All three corrected claims passed. Claim 1 (dedup scoped to Audiences, not tables): services/audiences/ writes only to Vitess/ClickHouse; Clay table rows in Postgres are never written to from any Audiences service path. Claim 2 (not automatic): confirmed by same DEFAULT_IMPORT_ACCOUNT_ALIAS_PRECEDENCE code + upsert-account.ts:92-99 showing fieldMatchingEntries only drive deterministic entries when admin has configured them. Claim 3 (Lookup in Audiences / Get Audiences Activity): confirmed at libs/shared/src/ActionDefinitions.ts:228-231, 243-246.

Uncertainties

The deterministic matching feature ("Import record matching" in the UI) is behind an Eppo flag (deterministic-record-matching) whose rollout targeting lives in the Eppo dashboard, not in the repo. Verifier returned UNKNOWN on which workspaces have it enabled. The existing doc already frames this as a beta feature requiring Growth Strategist enablement — the FAQ's anchor link to the "Entity resolution and deduplication" section routes users to that context. If the flag has since gone GA, the existing beta framing in the parent section should be updated separately.

Related observations

Three other PRs are currently open on docs/audiences.md: PR #1485 (Databricks import), PR #1507 (Snowflake/BigQuery field mapping note), PR #1528 (Salesforce custom object signal export). None overlap with the dedup scope FAQ added here.

Closes DOC-1138

[linear-code]

DOC-1138