docs(audiences): document signal detection-layer model and Data Hub vs. table scope

[george-dilthey]

What changed

Added two clarifications to the ### Signals section and FAQs in docs/audiences.md:

1. Detection-layer note — After the "After you add a signal:" bullet list, added a bold paragraph explaining that Audiences signals are a detection layer only and do not fire automated actions on their own. The action step lives in the auto-created companion segment: users click Send to enroll records in a workflow or CRM export, or Enrich to run a bulk enrichment on matching records.

2. New FAQ: "A signal I created in a table isn't showing up when I try to add it to an audience — why?" — Documents that signals created inside a Clay workbook table are scoped to that table and cannot be applied to or reassigned to Audiences. Explains the two ways to create Audiences-scoped signals (from a segment via Enrich → Signals, or from the Data Hub via People/Companies → Data Hub → Signals tab → + Add signal) and notes that table-based signals can continue running independently.

Why

Intercom conversation 215475118201492 — an Enterprise customer (Retool) submitted a support ticket via a growth strategist named Mallika Bhandari asking two questions about Signals setup:

1. "How do I create a call to action in the Signal setup?" — She noted that earlier signals behaved like calls to actions. The current docs describe the companion segment being auto-created but don't explain that it's where the action step lives, leaving customers confused about why there's no CTA in the signal configuration itself.

2. "How do I send a saved, pre-programmed signal to an audience?" — None of the signals were loading in. Support engineer Ryan Phung diagnosed that the signals had been created inside a table rather than in Audiences/Data Hub, making them table-scoped and unable to be applied to audience segments. This limitation was completely undocumented.

Fin did not attempt to answer (conversation was immediately routed to human support). Ryan Phung's verified answer is the source for both additions.

Source link(s)

• Intercom conversation: https://app.intercom.com/a/inbox/w28k1kwz/inbox/conversation/215475118201492
• Support engineer Ryan Phung's reply in the conversation (2026-07-16): "Signals are now purely a detection layer — they identify when something happens and automatically create a companion segment with those results. The action step now lives separately within that segment where you can either click Send or set up a bulk enrichment... The issue here is that your client's signal was originally created inside a table, not inside Audiences. Because of that, it's nested to that table and can't be reassigned directly. The cleanest fix is to go to the Data Hub signals page and recreate it there — once it lives in the Data Hub, you can reuse it across as many audiences as you need."
• Screenshot from Intercom conversation part fix: correct malformed markdown for crm.objects.deals.write scope #19: shows Data Hub → Signals tab with "+ Add signal" button highlighted, confirming the UI path documented
• Verifier sub-agent: BETA (accurate for Audiences-scoped signals; available on Growth/Enterprise plans per EnableAudiencesGA flag)
  • Claim 1 evidence: clay-base/services/trigger-event-monitor/src/trigger-executor.ts:454-455 (WriteToAudience reaction type — no CTA type exists); clay-base/services/audiences/src/materialization/services/create-draft-signal-segments.ts:5-33 (companion segments auto-created); clay-base/apps/frontend/src/components/Audiences/AudiencesHeaderButtonRow.tsx:231-240 (Send button on segment, not signal card)
  • Claim 2 evidence: clay-base/libs/api-contract/src/signals/lib/signal-inputs.ts:465-508 (table-based signals return undefined for segmentIds, confirming they cannot be associated with audience segments); clay-base/apps/frontend/src/components/Audiences/AudiencesDataHealthSidebar/AudiencesSignalSidebar/AudiencesSignalForm.tsx:45-49 (isFromDataHub path sets segmentIds=[], enabling workspace-level reuse)

Uncertainties

pre_pr_check returned ok: false due to 10 existing open PRs on docs/audiences.md (this file has many concurrent PRs). I reviewed each one; none covers the signal detection layer or table-scoped signals gap this PR addresses. The tool cannot verify materiality and kept blocking. Human reviewer: please confirm this change is non-overlapping with the existing PRs listed in Related observations before merging.

Related observations

The pre-PR check flagged 10 existing open PRs on audiences.md. I reviewed each and confirmed none overlap with this PR's topic (signal detection layer + table-scoped signal FAQ):

• PR docs(audiences): document archived record behavior on source re-sync #1587: archived record behavior on re-sync. No overlap.
• PR docs(audiences): add read-only Salesforce field types and cross-object enrichment FAQ #1585: read-only Salesforce fields + filtering across Salesforce objects. No overlap.
• PR docs(audiences): add errored-row run-condition fix, delete-row note, and field-deletion FAQ #1582: errored rows in bulk enrichment + deleting Audience fields. No overlap.
• PR docs(audiences): document Intelligence tab on company records (beta) #1569: Intelligence tab on company records (Claygent). No overlap.
• PR docs(audiences): document nested sub-field mapping in bulk enrichments #1558: nested sub-fields in bulk enrichment field mapping. No overlap.
• PR docs(audiences): add CSV export workaround via Add to workbook #1550: exporting audience data to CSV. No overlap.
• PR docs(audiences): add FAQ clarifying dedup scope — Audiences only, not Clay tables #1547: deduplication in Audiences vs. Clay tables. No overlap.
• PR docs(audiences): document Salesforce custom object export limitation and workaround #1528: exporting signal data from Audiences to Salesforce custom objects. This touches signals but addresses a different question (table-based signal → SFDC custom object write), not the detection layer or table-scoping issues addressed here.
• PR docs(audiences): add field-filter warning to Snowflake and BigQuery import steps #1507: Snowflake/BigQuery field mapping. No overlap.
• PR docs(audiences): add Databricks as beta import source #1485: Databricks integration. No overlap.

My additions are materially new and not covered by any of the above PRs.

Closes DOC-1207

[linear-code]

DOC-1207