docs(audiences): clarify Snowflake workflow trigger and add test-workspace note

[george-dilthey]

What changed

Added two notes to the Importing from Snowflake section of docs/audiences.md:

1. Workflow trigger clarification: Adding a Snowflake source does not directly trigger connected workflows — a workflow fires when a record first enters a connected segment, not when a source is added. Customers should build distinct segments per data source to keep automations separate.
2. Test workspace recommendation: Records imported into Audiences can only be archived (soft-deleted), not permanently removed self-serve. Recommends testing Snowflake imports in a test workspace before connecting a large dataset to production.

Why

Intercom conversation #215475691475593 was escalated to a human agent (Bo) after Fin answered correctly but the customer (Kylie Castaneda at Bubble, Enterprise plan) needed human confirmation on two points:

1. "So automations only work on the Audience level? AKA nothing will automatically run by adding the new source?" — Fin answered this partially, but the docs don't explicitly state the corollary: adding a Snowflake source does not directly trigger existing automations. The human agent (Bo) made this explicit.

2. Test workspace recommendation — Bo explicitly advised: "records can't be deleted from Audiences once imported, so if you want to test first, we'd recommend doing so in a test workspace." This guidance was not documented anywhere.

The conversation was classified: Tier_3_Ads_and_Audiences: Audiences – Source Connection, UX_Confusion: Knowledge Gap, AI Conversation Type: How-to.

Verifier results:

• CLAIM "only one Snowflake query per Audience": FAIL — not a code-enforced constraint. Backend supports multiple Snowflake imports with different queries (clay-base/apps/api/v3/audiences/services/audiences-snowflake-imports.service.ts:95-108 — prevents only exact duplicates, not different SQL). Not documented.
• CLAIM "records cannot be deleted once imported": PASS (with nuance) — Records can only be archived (soft-deleted) self-serve; permanent deletion requires Clay support. Already documented in the FAQ section. The test-workspace recommendation was not documented.
• Workflow trigger behavior is documented in the existing "Connecting a workflow to a segment" section (audiences.md ~line 530: "When a contact or company matches the segment's filters, the connected workflow starts within minutes") — but the explicit corollary ("adding a Snowflake source does not directly trigger") was missing from the Snowflake import steps where customers naturally read it.

Source link(s)

• Intercom conversation: https://app.intercom.com/a/inbox/w28k1kwz/inbox/conversation/215475691475593
• Human agent Bo's reply (conversation part #52739308172) provided the specific wording around workflow trigger behavior and test workspace recommendation.

Uncertainties

None — both additions are grounded in:

• Documented behavior (workflow trigger model from existing audiences.md "Connecting a workflow to a segment" section)
• Existing FAQ (archiving constraint from "What happens when I archive a record in Audiences?" section)
• Human agent's explicit recommendation in the Intercom conversation

Related observations

• 13 existing open PRs touch docs/audiences.md (docs(audiences): note that company fields don't carry through Find People to People records #2432, docs(audiences): document enrichment workflow beta option #2415, docs(audiences): document ad sync beta availability and per-workspace connections #2395, docs(audiences): replace non-existent Continue button with Upsert segment record instructions #2383, docs(audiences): add FAQ for moving audience segments between workspaces #2370, docs(audiences): document Salesforce export full-load behavior, API monitoring, and Last Enriched timestamp #2356, docs(audiences): document that Lookup in Audiences cannot scope to a segment, add workaround FAQ #2354, docs(audiences): document OR filter group with AND exclusion pattern #2349, docs(audiences): add archive cross-reference for Salesforce-deleted records #2348, docs(audiences): clarify legacy plan access and add why-not-visible FAQ #2345, docs(audiences): expand field mapping intent best practice to cover SFDC import sync path #2323, docs(audiences): add common HubSpot contact and company field examples #2321, docs(audiences): add FAQ for Salesforce duplicate company records #2305). Reviewed all; none cover the Snowflake import workflow trigger or test workspace recommendation. This change is materially new. Reviewers should reconcile against those PRs at merge time.
• Bo mentioned "currently only one Snowflake import query is supported per Audience" — verifier confirmed this is not a code-enforced constraint (multiple distinct queries ARE supported). This claim was not documented since it was inaccurate.
• The customer's broader question about multi-team (Sales + Marketing) Audiences setup is covered by the existing "Connecting a workflow to a segment" and "Conflict resolution" sections.

Closes DOC-2259

[linear-code]

DOC-2259