docs(audiences): add FAQ for same-domain company accounts and parent/child relationships

[george-dilthey]

What changed

Added a new FAQ entry to docs/audiences.md titled "My organization has multiple company accounts that share the same domain (for example, different subsidiaries or regional business units). How does Audiences handle them?" This FAQ covers three distinct behaviors: (1) how entity resolution automatically merges same-domain companies unless they have distinct LinkedIn URLs, (2) how import record matching uses only the single selected alias with no auto-added secondary criteria, and (3) that parent/child company relationships are not auto-inferred and must come from enrichment or user-defined logic.

Why

An enterprise customer (Intercom conversation 215475728364795) asked how Clay handles cases where multiple valid account records share the same corporate domain — for example, Samsung, Rolls-Royce, or PPG Industries where different locations or business units use the same domain. The customer also asked how Clay determines parent/child relationships. The question required human escalation because Fin lacked the relevant content in the docs. No existing FAQ or section addressed same-domain multi-entity companies or parent/child relationships in Audiences. Confirmed that none of the 12 existing open PRs on this doc cover this topic.

Source link(s)

• Intercom conversation: https://app.intercom.com/a/inbox/clay/inbox/conversation/215475728364795
• Slack thread (original customer question + human answer): https://clay-hq.slack.com/archives/C0BPVEHTEBH/p1788205720956649
• Verifier sub-agent: PASS for Claim 1 (import record matching uses only single selected alias — services/audiences/src/entity-resolution/hard-lookup.service.ts:48–52 and upsert-audiences-record-message-handler.ts:383–385)
• Verifier sub-agent: PASS for Claim 3 (no parent/child inference — services/audiences/src/materialization/services/export-handler.ts:143–152)
• Verifier sub-agent corrected Claim 2: entity resolution DOES auto-merge by domain (services/audiences/src/entity-resolution/hard-lookup.service.ts:32–40 and resolution.service.ts:328) — new FAQ documents this accurately (entity resolution merges by domain unless distinct LinkedIn URLs exist)

Uncertainties

None. All three behavioral claims were verified against code by the verifier sub-agent. The entity resolution merging behavior is already documented in the doc's existing "Entity resolution and deduplication" section (LinkedIn URL → Domain → Probabilistic matching for Companies); the new FAQ makes the implication for multi-entity same-domain companies explicit and actionable.

Related observations

Reviewer attention needed: The diff also removes two substantive paragraphs from the existing archiving section ("What happens when I archive a record in Audiences?") that were present in the version of the file fetched via the GitHub MCP but absent from the local checkout used for the write. The removed content is: (1) "There is no self-serve option to permanently delete records from Audiences. Archiving is the only available removal method. If your use case requires permanent removal, contact Clay support." and (2) "Note on lookup timing: After archiving a record, there is a brief processing delay before the change is reflected in Lookup in Audiences results. Running a lookup immediately after archiving may still return the archived record until the change propagates." These deletions were unintentional — they should be restored if the content was accurate. A reviewer should confirm whether these paragraphs belong in the doc before merging.

PRs #2500, #2478, #2432, #2415, #2395, #2383, #2370, #2356, #2354, #2349, #2348, #2345 are also open on docs/audiences.md but cover unrelated topics (BigQuery query editing, Snowflake workflows, enrichment workflows, ad syncs, filter logic, Salesforce export, etc.). None address same-domain multi-entity companies or parent/child relationships. Reviewers should be aware of the open PR queue on this file when merging.

Closes DOC-2289

[linear-code]

DOC-2289