@salesforce/afv-skills 1.63.0 → 1.65.0

package/skills/automation-flow-coordinate/references/elements/forward-to-bot-or-agent/forward-to-bot-or-agent.md

@@ -0,0 +1,274 @@
+---
+name: flow-element-forward-to-bot-or-agent
+license: LICENSE.txt has complete terms
+description: "Load when authoring a Forward to Bot/Agent element (`forwardToBotOrAgent` action call) in a marketing flow. Covers the mandatory WaitUntilEvent companion, the cross-element link via `associatedWaitConfiguration`, channel and event-type scoping, processType constraints (NOT Journey), and when to add a fault path. TRIGGER on: 'forward to bot', 'forward to agent', 'forwardToBotOrAgent', 'route replies to agent', 'conversational agent handoff', 'route inbound replies', 'send replies to bot'. DO NOT load for any other action call type."
+metadata:
+  version: "1.0"
+  related-skills: flow-element-action-call, flow-element-wait
+---
+
+# Forward to Bot/Agent
+
+`forwardToBotOrAgent` covers two distinct use cases. Identify the correct one before authoring anything.
+
+## Which mode do you need?
+
+| Mode | When to use | `modeSelector` wire value | WaitUntilEvent needed? |
+|---|---|---|---|
+| **Outreach Initiation (BEA)** | BEA sends the first email to a set of contactable records | `"InitiateConversation"` | **No** |
+| **Reply Routing** | Agent handles a customer's inbound reply to an upstream send | `"ManageReplies"` | **Yes** |
+
+- **"Forward to a Buyer Engagement Agent", "route contacts to BEA", "send email outreach via an agent"** → **Outreach Initiation**. Jump to [Outreach Initiation (BEA)](#outreach-initiation-bea). Skip "The Mandatory Pair" entirely.
+- **"Route replies to an agent", "handle customer responses"** → **Reply Routing**. The action must always follow an upstream send action and a matching WaitUntilEvent. Do not author it in isolation.
+
+## Reference File Index
+
+| File | Purpose |
+|---|---|
+| `examples/bea-outreach-initiation.json` | Outreach Initiation (BEA) forwardToBotOrAgent (`modeSelector: "InitiateConversation"`) + required flow-level metadata — no WaitUntilEvent |
+| `examples/forward-to-bot-or-agent.json` | Reply Routing: WaitUntilEvent (email response) + forwardToBotOrAgent pair — verified against live describe |
+
+## Outreach Initiation (BEA)
+
+Use `forwardToBotOrAgent` with `modeSelector: "InitiateConversation"` to have a Buyer Engagement Agent (BEA) send the first email to a set of contactable records (Individuals or Contacts for example). It runs in an `AutoLaunchedFlow`; a `Segment` trigger is the verified and most common case, but any trigger that supplies the audience works (see [processType Constraints](#processtype-constraints)). No WaitUntilEvent is needed.
+
+**Fixed action properties:**
+- `actionType` / `actionName` / `nameSegment`: `forwardToBotOrAgent`
+- `flowTransactionModel`: `"CurrentTransaction"`
+- `storeOutputAutomatically`: `true`
+- `outputParameters`: `[]`
+- `faultConnector`: omit (platform accepts without it; add a fault path if error handling is desired)
+- Requires an explicit `ends[]` terminal node; wire `connector.targetReference` to its `name`.
+- Set `areMetricsLoggedToDataCloud: true` at the top-level `metadata` for BEA outreach flows.
+
+### Parameters
+
+| Name | Type | Required | Notes |
+|---|---|---|---|
+| `channel` | string | **yes** | `"Email"` for email outreach |
+| `routingType` | string | **yes** | Always `"AgentforceServiceAgent"` for BEA outreach |
+| `agentId` | string | **yes** | BotDefinition record ID (`0Xx…`). Resolve via SOQL through `dispatch_readonly`: `{ url: "/services/data/vXX.0/query", method: "GET", queryParams: { q: "SELECT Id, MasterLabel, Type FROM BotDefinition" } }` — filter `Type = 'ExternalCopilot'` and match the agent by label. (Or, for a Data Cloud DMO lookup, the Data 360 tool `d360_query_sql` via `dispatch`: `dispatch({ url: "/services/data/vXX.0/ssot/mcp/execute", method: "POST", body: { toolName: "d360_query_sql", paramsJson: "{\"input\": {\"sql\": \"SELECT ssot__Id__c, ssot__DeveloperName__c FROM ssot__Bot__dlm LIMIT 10\"}}" } })`; the `ssot__Id__c` value is the BotDefinition ID.) Then verify the agent has an active version: `SELECT Id, Status FROM BotVersion WHERE BotDefinitionId = '<0Xx…>'` — at least one row must have `Status = 'Active'`. |
+| `modeSelector` | string | **yes** | `"InitiateConversation"` — exact wire value. Do NOT use `"Initial Outbound"`. |
+| `maxOutreachAttempts` | number | no | Nudge count (e.g. `3`). **Not returned by `GET /services/data/vXX.0/flowbuilder/action/invocable-action-details`** — set directly via `numberValue`. |
+| `timeBetweenOutreach` | number | no | Nudge interval in **minutes** (e.g. `60`). Not in descriptor; set via `numberValue`. |
+| `fromAddress` | string | **yes (runtime; schema-optional)** | `SenderEmailAddress` record ID (`35a…`). Resolve via SOQL: `SELECT Id, DisplayName, Username, IsAgentConversationalActive, MessagingChannelId FROM SenderEmailAddress` — pick a row where `IsAgentConversationalActive = true` and `MessagingChannelId` is non-null (those mark an agent-usable sender); match by `DisplayName`/`Username` to the intended sender. `GET /services/data/vXX.0/flowbuilder/action/org-wide-email-addresses` is unreliable for this (returns empty on many orgs) — use the SOQL query; if still blocked, ask the user for the record ID. **Required for the message to actually send — omitting it causes a silent send failure even when the flow validates and activates cleanly.** |
+| `communicationSubscriptionId` | string | **yes (runtime; schema-optional)** | `CommSubscription` record ID (`0Xl…`). Resolve via SOQL: `SELECT Id, Name FROM CommSubscription` — pick deliberately based on which subscription the outreach should send under (governs consent; do not just take the first row). **Required for the message to actually send — omitting it causes a silent send failure even when the flow validates and activates cleanly.** |
+
+> `maxOutreachAttempts`, `timeBetweenOutreach`, `fromAddress`, and `communicationSubscriptionId` are hidden parameters — they do **not** appear in `GET /services/data/vXX.0/flowbuilder/action/invocable-action-details` output. Do not call that tool expecting to find them; use the table above directly.
+
+**Dead-end tools — do not call for BEA outreach:**
+- `GET /services/data/vXX.0/flowbuilder/action/org-wide-email-addresses` — returns empty on some orgs; cannot reliably resolve `fromAddress` IDs
+- `GET /services/data/vXX.0/flowbuilder/action/invocable-action-parameter-enum-values` for `channelType` on `forwardToBotOrAgent` — always returns empty; `channelType` is not a parameter for this action (use `channel`)
+- `GET /services/data/vXX.0/flowbuilder/action/invocable-action-details` — will not surface the four hidden params listed above; don't spend tool calls waiting for them to appear
+
+### Silent send failure — the commonly-missed pair
+
+A flow with `forwardToBotOrAgent` can **validate clean and activate successfully — yet the message never sends**, either silently (flow reports "completed," no email delivered) or with:
+
+```text
+INTERNAL_ERROR: Message didn't send because internal error occurred while trying to send message
+```
+
+The usual cause: **`fromAddress` and `communicationSubscriptionId` are missing from the flow element**. The Agent Builder UI can display these as populated because they are inherited defaults from the agent — but a flow-level F2A element does **not** inherit those defaults. The flow must set both explicitly.
+
+> "Activated but nothing sent" → suspect missing `fromAddress` / `communicationSubscriptionId` first, before investigating channel setup, consent records, or audience membership.
+
+### Minimal example
+
+See `examples/bea-outreach-initiation.json` for the full fragment — the `forwardToBotOrAgent`
+ActionCall (all fixed properties and input parameters above) plus the flow-level `ends[]` and
+`areMetricsLoggedToDataCloud` metadata that a BEA outreach flow also requires.
+
+## The Mandatory Pair
+
+Every `forwardToBotOrAgent` must be preceded in the same flow by a `WaitUntilEvent`
+element that waits for a response to a specific upstream send. The two elements are
+linked by `associatedWaitConfiguration`.
+
+```text
+[Send action] → [WaitUntilEvent (response event)]
+                       │ event path        │ timeout path
+                       ▼                   ▼
+               [forwardToBotOrAgent]  [no-reply handler]
+```
+
+Build in this order: send action → WaitUntilEvent → forwardToBotOrAgent.
+
+**Channel scoping.** One send → one response WaitUntilEvent → one forwardToBotOrAgent.
+Match the wait event type to the *specific channel* the user asks to route replies
+from. If the user says "route replies from that email" and "you don't need to manage
+RCS replies", add only the email response pair — do not add an RCS pair.
+
+## Step 1 — WaitUntilEvent (Wait for Send Response)
+
+`elementSubtype: "WaitUntilEvent"`. Never approximate with a classic Wait or
+WaitDuration — engagement events cannot be bound on those types.
+
+### Event branch
+
+| Channel | `automationEventType` | `automationEventName` |
+|---|---|---|
+| Email reply | `trgrOnEmailResponseEngagement` | `trgrOnEmailResponseEngagement` |
+| SMS reply | `trgrOnSmsResponseEngagement` | `trgrOnSmsResponseEngagement` |
+| RCS reply | `trgrOnRcsResponseEngagement` | `trgrOnRcsResponseEngagement` |
+| WhatsApp reply | `trgrOnWhatsAppResponseEngmt` | `trgrOnWhatsAppResponseEngmt` |
+
+> **`automationEventName` = `automationEventType`** — confirmed via live retrieve. The `default__` prefix form (e.g. `"default__trgrOnEmailResponseEngagement"`) was not a valid value in the tested org; the platform stored `"NotFound"` when it was used — confirm this behavior holds in your target org.
+
+> Always confirm what events are provisioned in the org before authoring — the table above reflects one org's baseline. Use **`GET /services/data/vXX.0/flowbuilder/action/invocable-events`** with `processType: "AutoLaunchedFlow"` and `triggerType: "Segment"` (the Connect OAS param names — NOT `flowProcessType`/`flowTriggerType`). It returns `invocableActions[]`; use each entry's `type` as `automationEventType` and `name` as `automationEventName`.
+
+**`associatedContent` is required** on every messaging response event's
+`inputParameters`. Bind it by `elementReference` to the upstream send action element
+(not a string template ID):
+
+```json
+"inputParameters": [
+  { "name": "associatedContent", "value": { "elementReference": "Send_Marketing_Email" } }
+]
+```
+
+Omitting `associatedContent` blocks activation:
+`"Required parameter 'associatedContent' is missing or empty"`.
+
+Set `recordTriggerType: "Create"` on the event branch. Do **not** set `offset` on the event branch — omit it (leave null). Setting `offset: 0` is rejected or stored as a no-op.
+Leave `outputParameters: []` — the agent handles the inbound message; there is
+nothing to capture here for the forward pattern.
+
+### Timeout branch
+
+Route the timeout branch to a "no reply received" path.
+
+| Field | Value |
+|---|---|
+| `offset` | 1–365 (required) |
+| `offsetUnit` | `Days` / `Hours` / `Weeks` |
+| `inputParameters` | `[]` |
+| `outputParameters` | `[]` |
+
+### Required shape rules (see also `../wait/wait.md`)
+
+- `defaultConnectorLabel: "Default"` — required even on simplified subtypes or save
+  is rejected (`Required field is missing: defaultConnectorLabel`).
+- No `defaultConnector`, no `faultConnector` on `WaitUntilEvent`.
+- No `maxBatchSize` — rejected on `AutoLaunchedFlow`.
+- The **event-branch waitEvent's `name`** is the value you reference in Step 2.
+
+## Step 2 — forwardToBotOrAgent ActionCall
+
+```text
+actionType: "forwardToBotOrAgent"
+actionName: "forwardToBotOrAgent"
+hasCallout:  true   →   marketing flow: faultConnector only when the user asks for error handling; any other flow type: wire one
+isAsync:     false
+allowsTransactionControl: true
+```
+
+### Parameters
+
+| Name | Required | Type | Notes |
+|---|---|---|---|
+| `channel` | **yes** | string | Messaging channel. No static picklist — verify at author time. Describe says valid values include `"SMS"` and `"WhatsApp"`; use `"Email"` for email-reply routing (confirm per org). |
+| `associatedWaitConfiguration` | **yes** | CrossElementRef | Reference to the event-branch waitEvent in the preceding WaitUntilEvent — see syntax below |
+| `messagingChannelId` | no | string | Marked `configurationOnly` — `elementReference` is rejected at save time (`INPUTPARAM_INCOMPATIBLE_CONFIGURATION_ONLY`). Cannot be set to `$Context.MessagingChannelId` via element reference. Omit unless you have a static channel ID to hard-code. |
+| `agentId` | no | string | ID of the Agentforce Service Agent or bot |
+| `routingType` | no | string | `"Omni Flow"`, `"Omni Queue"`, or `"AgentforceServiceAgent"` (confirmed enum value for routing to an Agentforce Service Agent) |
+| `modeSelector` | no | string | `"InitiateConversation"` for BEA Outreach Initiation (verified via `GET /services/data/vXX.0/flowbuilder/action/invocable-action-details` on `forwardToBotOrAgent`). `"Initial Outbound"` is **NOT** a valid wire value. For Reply Routing, use `"ManageReplies"`. |
+
+Output: `messageId` (string) — ID of the inbound message. Capture via
+`storeOutputAutomatically: true`.
+
+### `associatedWaitConfiguration` syntax
+
+The value is the WaitUntilEvent element's **`name`** — the API name of the Wait element only, not including any event name suffix:
+
+```json
+{
+  "name": "associatedWaitConfiguration",
+  "value": { "stringValue": "Wait_For_Email_Reply" }
+}
+```
+
+> `associatedWaitConfiguration` has `complexType: "CrossElementRef"` in the action descriptor — that is a Flow Builder UI hint, not a wire-format directive. The Tooling API rejects `elementReference` here with `INPUTPARAM_INCOMPATIBLE_CONFIGURATION_ONLY`. Always use `stringValue` with the element name alone (no `.EventName` suffix).
+
+### Connector and fault connector
+
+A forward `connector` to the next element (or an End node) is **required** — omitting it leaves the action with no exit path and the flow will be invalid. *(When the forward target is an End in `AUTO_LAYOUT_CANVAS` at resolved `apiVersion` ≥ 68.0, point the connector at an explicit `ends[]` End — its own dedicated End or a shared End converged with other non-fault branches, both valid; below 68.0 and on any Free-Form flow, omit the connector instead. See `shared/anti-patterns.md` item 38 and `shared/end/end.md`.)*
+
+`hasCallout: true` — the action can throw at runtime on routing failures. It usually runs in a marketing flow (a `Segment` or `IndivRelatedRecord` trigger). There, add a `faultConnector` only when the user asks for error handling; the platform accepts the action without one. In any other flow type, wire one (the default rule). See `shared/fault-paths/fault-paths.md` § Marketing Flows — Fault Paths Only When Asked.
+
+### Example `inputParameters`
+
+```json
+"inputParameters": [
+  { "name": "channel",                     "value": { "stringValue": "Email" } },
+  { "name": "associatedWaitConfiguration", "value": { "stringValue": "Wait_For_Email_Reply" } },
+  { "name": "agentId",                     "value": { "stringValue": "<agent-id>" } }
+]
+```
+
+## processType Constraints
+
+| processType | triggerType | Supported |
+|---|---|---|
+| `AutoLaunchedFlow` | `Segment` | **yes** — confirmed via `GET /services/data/vXX.0/flowbuilder/action/invocable-actions` |
+| `AutoLaunchedFlow` | `IndivRelatedRecord` | likely yes — same catalog; confirm with `GET /services/data/vXX.0/flowbuilder/action/invocable-actions` |
+| `Journey` | — | **NO** — `Journey` (label: "Audience-Driven Flow") does not support `forwardToBotOrAgent` or `WaitUntilEvent`; do not use it |
+
+When the user's request involves a segment, audience, or marketing flow: use
+`processType: AutoLaunchedFlow` + `triggerType: Segment`. Never use `Journey`.
+
+Always confirm at author time: `dispatch_readonly(method: "GET", url: "/services/data/vXX.0/flowbuilder/schema/flow-capabilities", queryParams: { processType, triggerType })` and
+verify both `WaitUntilEvent` and `ActionCall` appear in `.elements`.
+
+## Anti-Patterns
+
+```jsonc
+// WRONG #1 — forwardToBotOrAgent with no preceding WaitUntilEvent in REPLY ROUTING mode.
+// Applies ONLY when the intent is to route a customer's inbound reply to an agent.
+// For modeSelector="InitiateConversation" (BEA Outreach Initiation in a Segment flow),
+// NO WaitUntilEvent is needed or expected — omitting it is correct.
+
+// WRONG #2 — Missing associatedContent on the WaitUntilEvent event branch.
+// Blocks activation: "Required parameter 'associatedContent' is missing or empty".
+{ "automationEventType": "trgrOnEmailResponseEngagement", "inputParameters": [] }
+
+// WRONG #3 — associatedWaitConfiguration using elementReference.
+// The parameter is configurationOnly; elementReference is rejected with
+// INPUTPARAM_INCOMPATIBLE_CONFIGURATION_ONLY. Always use stringValue.
+{ "name": "associatedWaitConfiguration", "value": { "elementReference": "Wait_For_Email_Reply" } }
+// must be:
+{ "name": "associatedWaitConfiguration", "value": { "stringValue": "Wait_For_Email_Reply" } }
+
+// WRONG #4 — associatedWaitConfiguration with dot-notation value.
+// The "ElementName.WaitEventName" form is rejected — use the element name alone.
+{ "name": "associatedWaitConfiguration", "value": { "stringValue": "Wait_For_Email_Reply.Email_Reply_Event" } }
+// must be:
+{ "name": "associatedWaitConfiguration", "value": { "stringValue": "Wait_For_Email_Reply" } }
+
+// WRONG #5 — The user asked for error handling, but forwardToBotOrAgent has no faultConnector.
+// hasCallout is true. When the user did not ask and the flow is a marketing flow (the usual case for
+// Reply Routing and BEA Outreach Initiation), omit it. In any other flow type, always wire one.
+{ "actionName": "forwardToBotOrAgent", "connector": { "targetReference": "End" } }
+// faultConnector missing
+
+// WRONG #6 — processType Journey.
+// Journey does not support forwardToBotOrAgent or WaitUntilEvent.
+
+// WRONG #7 — Adding an RCS WaitUntilEvent when the user said
+// "you should not need to manage RCS replies".
+// Only build the pair for channels the user explicitly wants to route.
+
+// WRONG #8 — flowTransactionModel: "Automatic".
+// Does NOT fix a send failure. It moves the transaction boundary so the
+// runtime error is swallowed and the flow reports "success" while still
+// sending nothing. Keep "CurrentTransaction" so real send errors surface.
+```
+
+## Debugging — "activated but not sending"
+
+When the flow activates cleanly but no message is delivered:
+
+1. **Audience**: verify the segment contains records with a valid, non-opted-out address.
+2. **Active agent version**: `SELECT Id, Status FROM BotVersion WHERE BotDefinitionId = '<0Xx…>'` — at least one row must be `Active`.
+3. **Missing send parameters**: confirm `fromAddress` and `communicationSubscriptionId` are both present on the F2A element and each resolves to a current, valid record (re-query `SenderEmailAddress` / `CommSubscription` as shown in the parameters table above). A missing or stale value in either is the prime suspect.
+4. **Transaction model**: confirm `flowTransactionModel` is `CurrentTransaction`, not `Automatic` — `Automatic` swallows the runtime send error so the flow reports success while sending nothing.

package/skills/automation-flow-coordinate/references/elements/start/audience-common.md

@@ -0,0 +1,192 @@
+---
+name: flow-element-start-audience-common
+license: LICENSE.txt has complete terms
+description: "Shared build contract for ALL audience-triggered flows — the run schedule, top-level `timeZoneSidKey`, top-level `dataSpace`, optional `dataGraph`, re-entry (`entryType`), the save-and-activate gates, and the builder round-trip defaults common to `triggerType` `Segment`, `List`, `CampaignMember`, and `RecordQuery` (they all share Core's `BaseAudienceTriggerTypeHandler`). Load this FIRST, then load the per-trigger binding guide: `segment-triggered.md`, `list-campaignmember.md`, or `recordquery.md`. Covers only what is identical across the four; the audience binding and record context live in the per-trigger files. DO NOT load for RecordAfterSave, Scheduled, PlatformEvent, or any non-audience trigger."
+metadata:
+  version: "1.0"
+  related-skills: flow-element-start, flow-flow-properties, flow-element-wait
+---
+
+# Audience-Triggered Flows — Shared Contract
+
+Load this **first** for any audience-style trigger, then load the matching
+binding guide for how the audience is bound and referenced:
+
+| Trigger | UI name | Audience | Binding guide |
+|---|---|---|---|
+| `Segment` | Segment Flow | a marketing **Segment**'s individuals (Data Cloud) | `segment-triggered.md` |
+| `List` | List Flow | an **Actionable List**'s members | `list-campaignmember.md` |
+| `CampaignMember` | Campaign Member Flow | a **Campaign**'s members (Contacts/Leads) | `list-campaignmember.md` |
+| `RecordQuery` | Record Query | **all records of one SObject** matching a filter | `recordquery.md` |
+
+All four enter an audience of members when the flow runs and share one Core base
+— `BaseAudienceTriggerTypeHandler` (→ `DefaultScheduledTriggerTypeHandler`) —
+which is why the run schedule, `timeZoneSidKey`, `dataSpace`, `dataGraph`,
+`entryType`, and the save-and-activate gates below are **identical** across them.
+The only per-trigger differences are the **audience binding** and the
+**record-context handle** — both documented in the per-trigger guides.
+
+## Reference File Index
+
+| File | Purpose |
+|---|---|
+| `examples/segment-weekly-schedule.json` | Weekly run-schedule start-element example (schedule shape is shared by all four triggers) |
+| `segment-triggered.md` | Bind + reference a `Segment` audience |
+| `list-campaignmember.md` | Bind + reference a `List` or `CampaignMember` audience |
+| `recordquery.md` | Bind + reference a `RecordQuery` audience |
+
+## processType, activation, and Draft status
+
+- **processType** is always `AutoLaunchedFlow` for all four triggers. Author it for
+  both `POST /services/data/vXX.0/flowbuilder/flow/actions/save` and legacy `saveAndValidateFlow`
+  lifecycles. Do not substitute `Journey` based on the builder surface name or a
+  Connect enum member.
+- Keep `processType: "AutoLaunchedFlow"` when activation must happen in the UI. A
+  save yields a **Draft**; activation is a user action in the builder (the
+  `POST /services/data/vXX.0/flowbuilder/flow/{flowId}/actions/activate` endpoint (activateFlow — DO
+  NOT DISPATCH, quarantined) is disabled for every flow type — a 404 from it does
+  NOT indicate a process-type mismatch). Open the version with
+  `builderType=JourneyBuilder` and let the user activate it there. See
+  `../../shared/preview-renderer.md`.
+- With the Core HTTP lifecycle, **omitting `start.triggerType`** makes Core
+  validate the flow as a plain autolaunched flow; audience-only actions then fail
+  with `ACTIONCALL_NOT_SUPPORTED_FOR_PROCESSTYPE`. Always set the trigger type.
+- A Core save with `isSuccess: true` and `status: "InvalidDraft"` is **not**
+  complete. Fix every missing/blocking warning and save again until
+  `status: "Draft"`. A save returning `isSuccess: true` **with warnings** is not
+  "done" — clear all four `WARNING_BLOCK_ACTIVATION` gates below or the draft
+  can't be activated.
+
+## Requirements to save-and-activate (all four triggers)
+
+Inherited from `BaseAudienceTriggerTypeHandler`. Each validates as
+`isSuccess: true` even while missing, but each is a `WARNING_BLOCK_ACTIVATION`
+that stops the draft going live — set all four on the **first** save:
+
+1. **Audience selection** — per-trigger; see the binding guide. (`Segment`:
+   `start.segment` + `start.object`; `List`/`CampaignMember`: `start.listAction`;
+   `RecordQuery`: `start.object`.) Each has its own missing-audience error.
+2. **Run schedule** — `start.schedule.frequency` is required (see [Run schedule](#run-schedule)).
+   Missing → `FLOW_SCHEDULE_INFORMATION_INCOMPLETE`.
+3. **Time zone** — top-level `metadata.timeZoneSidKey` (see [timeZoneSidKey](#timezonesidkey--top-level-and-required)).
+   Missing → `TIME_ZONE_REQUIRED_FOR_TRIGGER_TYPE`.
+4. **Data space** — top-level `metadata.dataSpace` (see [Set the data space](#set-the-data-space)).
+   Missing → `DATA_SPACE_REQUIRED_FOR_FLOW_TYPE`.
+
+Fault paths are **not** among these requirements. An audience-triggered flow is
+a marketing flow: add a `faultConnector` or error-handling branch only when the
+user asks for error handling. A flow with no fault paths saves and activates.
+See `../../shared/fault-paths/fault-paths.md` § Marketing Flows — Fault Paths Only When Asked.
+
+## Run schedule
+
+An audience flow's cadence is its **run schedule** (`start.schedule`) — NOT a
+Scheduled-flow trigger. The fields below are the ones the platform's validator
+actually checks, and its feedback is misleading: it reports a *missing* timezone
+when the value is merely mis-placed, and conditional-field errors only surface
+after a save. So a wrong shape almost never self-corrects — get it exact up front.
+
+- **`frequency: "OnActivate"`** runs when the flow is activated and needs **no**
+  `startDate`/`startTime` — the right default when the prompt names no cadence.
+- Every other frequency needs `startDate` + `startTime`.
+
+| Field | Type | When | Notes |
+|---|---|---|---|
+| `frequency` | string | always | One of `OnActivate`, `Once`, `Hourly`, `Daily`, `Weekdays`, `Weekly`, `Monthly`, `Yearly` |
+| `startDate` | string (date) | always (except `OnActivate`) | e.g. `"2026-06-01"` |
+| `startTime` | string (time) | always (except `OnActivate`) | e.g. `"09:00:00.000"` |
+| `frequencyNumber` | integer ≥ 1 | required for `Hourly`, `Weekly`, `Monthly` | number of units between runs |
+| `daysOfWeekToRun` | string | required for `Weekly` | numeric day codes — see below |
+| `dayOfMonthToRun` | integer | required for `Monthly` | `1`–`31`, or `-1` for last day of month |
+
+- **`Weekly`:** set `frequencyNumber` (integer ≥ 1) **and `daysOfWeekToRun` as a comma-separated string of numeric day codes** — **1=Sunday, 2=Monday, 3=Tuesday, 4=Wednesday, 5=Thursday, 6=Friday, 7=Saturday.** Use the NUMBER, not the day name, and not a list: "every Tuesday" → `"3"`; "Monday and Wednesday" → `"2,4"`; "Tuesday and Thursday" → `"3,5"`. The platform enforces the regex `^([1-7](,[1-7])*)$`; a day name like `"Tuesday"` is rejected with "Enter a valid value for the Days of Week to Run field."
+- **`Monthly`:** set `dayOfMonthToRun` (a scalar integer `1`–`31`, or `-1` for the last day). `dayOfMonthToRun` is allowed ONLY for `Monthly`.
+- **`Daily` takes NO `frequencyNumber`.** `frequencyNumber` is allowed only for `Hourly`, `Weekly`, and `Monthly` — setting it on a `Daily` (or `Weekdays`/`Yearly`/`Once`) schedule fails with `INVALID_FIELD_FOR_CONFLICTING_FIELD_VALUE`. **There is no N-day-interval frequency**: "every 3 days" is NOT expressible as a single schedule. Model it as plain `Daily` (dropping the interval) or with an in-flow `Wait` loop — do NOT emit `Daily` + `frequencyNumber: 3`.
+- **`Weekdays`** is a standalone frequency meaning Monday–Friday. It takes neither `frequencyNumber` nor `daysOfWeekToRun` — both are rejected.
+- **Value caps:** `Hourly` `frequencyNumber` ≤ 168; `Monthly` `frequencyNumber` ≤ 12; both ≥ 1. `dayOfMonthToRun` out of range (not 1–31 and not -1) fails with `WAITEVENT_INVALID_VALUE`; a malformed `daysOfWeekToRun` string fails with `FLOW_START_INPUT_REQUIRED`.
+
+### Worked example — "every Tuesday and Thursday at 9 AM Eastern"
+
+See `examples/segment-weekly-schedule.json` for the start-element shape — note
+`daysOfWeekToRun` is the numeric-code string `"3,5"` (Tue + Thu), never
+`["Tuesday","Thursday"]`. The required `timeZoneSidKey` (`"America/New_York"`) is
+**not** part of that snippet: it lives at the flow's top level
+(`metadata.timeZoneSidKey`, a sibling of `start`), per the placement rule below —
+never inside `schedule` or on the Start element.
+
+## timeZoneSidKey — top-level and REQUIRED
+
+- **`timeZoneSidKey` is a REQUIRED top-level flow property — a sibling of `start` inside `metadata` (`metadata.timeZoneSidKey`), NEVER `start.timeZoneSidKey`.** Both omitting it and mis-placing it on the start element fail as `TIME_ZONE_REQUIRED_FOR_TRIGGER_TYPE` (the placement error misleadingly reads as "no timezone supplied").
+- Value is an IANA timezone id, e.g. `"America/New_York"`. A bogus id fails with `INVALID_TIME_ZONE`.
+- **Which value when the user is silent: default to the org default timezone — do NOT ask the user to pick one.** Resolve the org default from the org itself (`SELECT TimeZoneSidKey FROM Organization`, the running user's `TimeZoneSidKey`, or the `timeZoneSidKey` on an existing active flow in the org). Only use a specific IANA id when the user explicitly names a timezone. Because an audience flow *cannot* omit `timeZoneSidKey` (unlike a plain AutoLaunchedFlow, which must omit it), "default timezone" here means **auto-fill the org default**, never blank. See the Wait timezone rule in `../wait/wait.md`.
+
+## Set the data space
+
+Required. Set `dataSpace` on the **top-level** flow object (`metadata.dataSpace`,
+API ≥ 258) to a data space's `name` (e.g. `"default"`), resolved through `dispatch`/`dispatch_readonly` by
+**either** path:
+- SOQL via `dispatch_readonly({ url: "/services/data/vXX.0/query", method: "GET", queryParams: { q: "SELECT Id, Name FROM DataSpace" } })` → `records[]`, each `{Id, Name}`. Use `Name`.
+- the Data 360 tool `d360_dataspace_list` (`dispatch` POST to `/services/data/vXX.0/ssot/mcp/execute`, `paramsJson: "{\"batchSize\": 50, \"offset\": 0}"`) → `result.dataSpaces[]`, each `{id, label, name, status}`. Use `name`, not `id` or `label` — this path also yields `label`/`status`.
+
+1. Only one data space → use it silently.
+2. Multiple + user specified one → match by `name`/`label` and use that.
+3. Multiple + user didn't specify → ask which data space to use. Do not guess a default.
+
+- **List/CampaignMember/RecordQuery audiences are Core records (ActionableList / Campaign / an SObject), not Data-Cloud assets, so their home data space isn't resolvable through the Data 360 tool** — default to the org default and surface the assumption at the plan gate. The SOQL path above still resolves the data space itself either way.
+- For `sendToJourney` (a Segment flow), also require the selected business unit's `businessUnitsToDataSpaces[].dataSpaceName` to equal this `name`. Follow `../action-call/send-to-journey.md` for business-unit and Journey selection.
+
+## Set the data graph
+
+Optional. Set `dataGraph` on the **start element** (`metadata.start.dataGraph`) to
+a data graph's `developerName`, resolved via the Data 360 tool
+`d360_datagraph_metadata` (`dispatch`): `dispatch({ url: "/services/data/vXX.0/ssot/mcp/execute", method: "POST", body: { toolName: "d360_datagraph_metadata", paramsJson: "{\"dataspace\": \"<the dataSpace name from above>\"}" } })` → `result.dataGraphMetadata[]`, each `{developerName, dataspaceName, dgObject: {developerName: <backing DMO>, relatedObjects: [...], ...}}`. Omit
+`dataGraphEntityName` in `paramsJson` to list every graph in that data space; add a
+specific `"dataGraphEntityName"` to fetch just that graph's full schema. (This
+metadata tool is the source for the graph's backing DMO and related-object schema;
+a `DataGraph` SOQL query returns only `DataGraphApiName`/`PrimaryDmo`/`Status`, not
+`relatedObjects`.)
+
+1. User specifies a data graph → use its `developerName`. If no data space was specified, use that graph's own `dataspaceName`.
+2. User specifies both → verify the graph's `dataspaceName` matches the data space chosen above. If it doesn't, ask the user how to proceed.
+3. User does NOT specify a data graph → leave it blank.
+
+## Re-entry — `entryType` on the Start element
+
+`entryType` governs whether — and *when* — a single member who has **already
+entered** the flow may enter it **again**. Omit unless the prompt restricts re-entry.
+
+| Re-entry for a member who already entered | `entryType` |
+|---|---|
+| may enter again any time, even while a prior run is still in progress (default) | omit (= `Always`) |
+| may enter again, but only after finishing the current run — no two overlapping runs for the same member | `AfterCompletion` |
+| may never enter more than once | `Never` |
+
+Write `entryType` only as `AfterCompletion` or `Never`. When the prompt says
+nothing about re-entry, leave `entryType` out of the Start. A made-up value such
+as `AllRecords` stops the flow from activating: `'AllRecords' is not a valid value for the enum 'FlowEntryType'`.
+
+## Record context ($Input / $Record) — globals available
+
+The **per-trigger member handle** is documented in each binding guide, because it
+differs by trigger: List / CampaignMember / RecordQuery expose the member row on
+`$Input.…`; **Segment exposes the member as `$Record`** (a row of the segment's DMO,
+e.g. `$Record.ssot__FirstName__c`; see `segment-triggered.md`). The global
+availability:
+
+| Global | Available? | Notes |
+|---|---|---|
+| `$Input` | Yes for List / CampaignMember / RecordQuery; No for Segment | Trigger-input container. Member handle is per-trigger; **not** exposed for Segment. |
+| `$Record` | Segment only | In a Segment flow, the current member (a row of the `segmentOnApiName` DMO): write `$Record.<field>`, never the bare field name. Not available for List / CampaignMember / RecordQuery. |
+| `$Contact` / `$Lead` / `$Prospect` | No | Not exposed for audience triggers — use `$Input` (List/CampaignMember/RecordQuery) or `$Record` (Segment). |
+| `$Flow.*` | Yes | `CurrentDate`, `CurrentDateTime`, `InterviewStartTime`, `InterviewGuid`, `FaultMessage` |
+
+## What the builder normalizes on save (round-trip defaults)
+
+A save through the builder rewrites the metadata with a default skeleton.
+Engine-supplied — do NOT hand-author, and don't treat their appearance on a
+retrieve as drift:
+
+- **Metadata level:** `accessType: "NamespaceRestricted"`, `areMetricsLoggedToDataCloud: true`, every element collection present as `[]`.
+- **`schedule`** with `OnActivate`: `dayOfMonthToRun: 0`, `frequencyNumber: 0` (zero placeholders — not a cadence).
+- The save stays on the same Draft version (no new version created).
+- The **per-binding** skeleton (the `listAction` FlowActionCall fields, or the RecordQuery Start skeleton) is documented in the binding guides.

package/skills/automation-flow-coordinate/references/elements/start/automation-event-triggered.md

@@ -0,0 +1,130 @@
+---
+name: flow-element-start-automation-event-triggered
+license: LICENSE.txt has complete terms
+description: "Load when building an Automation Event-triggered flow — triggerType `AutomationEvent`, processType `AutoLaunchedFlow` — that FIRES when an email-engagement event occurs (email open, link click, bounce, or response). Covers discovering the event at runtime (`GET /services/data/vXX.0/flowbuilder/action/invocable-events` + describe), the start-element shape (`eventName`/`eventType`), the inputs that make the flow activatable, and the hard line between an event-TRIGGERED flow (this) vs a flow that WAITS mid-flow on an engagement event (IndivRelatedRecord + WaitUntilEvent) vs a PlatformEvent flow. NOT for Marketing form submission — Flow Builder lists Form Submission under Automation Event, but it is triggerType `FormSubmissionEvent` (load `form-submission-triggered.md`). DO NOT load for any other trigger type."
+metadata:
+  version: "1.0"
+  related-skills: flow-element-start, flow-flow-properties
+---
+
+# Automation Event-Triggered (OOTB Email-Engagement Flow)
+
+Load this when `triggerType` is `AutomationEvent`. It is the complete build guide for the Automation Event start element; the base `start.md` carries only the routing stub.
+
+The whole flow FIRES when an email-engagement event occurs for an individual — an email is opened, a link is clicked, the email bounces, or the recipient responds.
+
+- **triggerType**: `AutomationEvent`. Author **`processType: "AutoLaunchedFlow"`** (headless). Do not substitute `Journey` based on the builder surface name.
+- The event is chosen ON the start element via **`eventName` + `eventType`** — NOT `actionName`/`actionType`, which match neither element (a mid-flow Wait Until Event uses its own `automationEventName`/`automationEventType`, and the start uses `eventName`/`eventType` — see the disambiguation below).
+- Requires a Marketing/engagement-provisioned org: the Automation Event trigger and its events are license-gated and do not exist on a plain org. If the trigger type or an event is unavailable, STOP and tell the user the org is not provisioned — do NOT fall back to another trigger type.
+
+## Discover the event — don't hard-code it
+
+Automation Events run on the same invocable-action framework as Action Call actions, so you discover them the same way you discover actions: list what the org offers, then describe the one you pick. Treat discovery as the source of truth for the event's trigger string and its inputs; the event-specific notes later in this file cover only the handful of things discovery does NOT tell you.
+
+> **One shared discovery endpoint — read this before using it.** `invocable-events` is the org's single event-discovery endpoint, and its API description is written around the Wait-Until-Event case ("the events a Wait Until Event element can wait on"). It nonetheless enumerates the SAME engagement/automation event catalog that the AutomationEvent **start** trigger fires on — there is no separate start-trigger discovery endpoint. The only difference is how the discovered event is referenced downstream: an AutomationEvent **start** uses the BARE `trgrOn…` value in `eventName`/`eventType` (this guide), whereas a mid-flow Wait Until Event uses the `default__`-prefixed form in `automationEventName`/`automationEventType` (see `../wait/wait.md`). So discover the event here, then put the **bare** value on the start.
+
+1. **List the available events.** Call `dispatch_readonly(method: "GET", url: "/services/data/vXX.0/flowbuilder/action/invocable-events", queryParams: { processType: "AutoLaunchedFlow" })` to enumerate the engagement/automation events the org actually exposes. Read the descriptors from the response `invocableActions[]` — each row's `name` is the event's exact trigger string (its `type` echoes the same value). Match the user's intent (opened / link clicked / bounced / responded) to a row and take its exact `name`. Do NOT guess or hard-code the string — use what discovery returns. (Optional query params to narrow the list: `triggerType`, `builderType`, `dataSpace`, `actionType`, `namePattern`, `limit`.)
+2. **Set the trigger identity from it.** Put that exact string in BOTH `eventName` and `eventType` (they always carry the identical value — see Start element shape).
+3. **Describe the chosen event to learn its inputs.** Call `dispatch_readonly(method: "GET", url: "/services/data/vXX.0/flowbuilder/action/invocable-action-details", queryParams: { actionType: "<the row's type>", actionName: "<the row's name>" })` for the event. The describe output lists its input parameters and marks which are required (`isRequired`). For the email-engagement events this is where `associatedContent` (and, for link click, `specificLink`) come back as required inputs — read them from describe rather than assuming. See "Fill the required inputs" below for the values these inputs expect.
+
+If `GET /services/data/vXX.0/flowbuilder/action/invocable-events` returns nothing or the intended event is missing, the org is not engagement-provisioned — STOP and tell the user (see the provisioning note above).
+
+> **Form Submission is not built here.** When discovery is scoped to `triggerType: "AutomationEvent"`, it also returns a `trgrOnFormSubmission` row labeled "Form Submission". Never put it in `eventName`/`eventType` — that shape is rejected (invalid event name, `InvalidDraft`). A flow that runs when someone submits a Marketing form is `triggerType: FormSubmissionEvent`; STOP here and load `form-submission-triggered.md`.
+
+## Do NOT confuse with the look-alikes
+
+**Choosing between these is a flow-type classification decision — owned by the
+flow-type-resolver reference (`../../shared/flow-type-resolver/flow-type-resolver.md`).**
+Fire-on-event vs. run-then-wait is its `taxonomy.json`
+fire-on-event-vs-run-then-wait bad pair, and the `AutomationEvent` / `IndivRelatedRecord`
+(+ `Segment`) / `PlatformEvent` types are its categories; resolve there, not here. Once the
+type is resolved, this is the build detail — **where the event is set** for each:
+
+| Trigger type | Where the event is set |
+|---|---|
+| `AutomationEvent` start (this guide) — flow FIRES when an email is opened/clicked/bounced/responded-to | `eventName`/`eventType` on the **start** |
+| `IndivRelatedRecord` (or `Segment`) + a `WaitUntilEvent` element — flow runs first, then PAUSES until the engagement event (see `start.md` and `../wait/wait.md`) | `automationEventName`/`automationEventType` on the **wait** element |
+| `PlatformEvent` start — react to a Platform Event (`__e`) message | `object` = event API name (never `eventName`/`eventType`) |
+| `FormSubmissionEvent` start — flow FIRES when someone submits a Marketing form (listed under Automation Event in Flow Builder, but NOT an `AutomationEvent`; see `form-submission-triggered.md`) | `form` = the form's content FQN on the **start** (never `eventName`/`eventType`) |
+
+Do NOT resolve marketer intent to **`AdminAutomationEvent`** — that is a separate admin variant, not the OOTB engagement trigger.
+
+## Start element shape
+
+| Field | Value |
+|---|---|
+| `triggerType` | `"AutomationEvent"` |
+| `eventName` | the event's exact trigger string — from discovery (see above) |
+| `eventType` | the SAME trigger string as `eventName` (both fields carry the identical value in every saved Automation Event flow) |
+| `processType` (flow root) | `"AutoLaunchedFlow"` |
+
+**Required:** start `inputs[]` (`associatedContent`, plus `specificLink` for link-click) and a flow-level `dataSpace` — see [Fill the required inputs](#fill-the-required-inputs--start-inputs--data-space) below; without them the flow saves but comes back `InvalidDraft`. Optional: entry `conditions`/`conditionLogic` (default: No Conditions). `$Event` is available in the flow body once `eventName`/`eventType` are set.
+
+```json
+"start": {
+  "locationX": 0, "locationY": 0,
+  "triggerType": "AutomationEvent",
+  "eventName": "trgrOnEmailOpenEngagement",
+  "eventType": "trgrOnEmailOpenEngagement",
+  "connector": { "targetReference": "<first element>", "isGoTo": false }
+}
+```
+
+*Note: the snippet above shows the trigger-identity fields only (the event string is illustrative — use the one `GET /services/data/vXX.0/flowbuilder/action/invocable-events` returns). A valid, activatable flow also needs the start `inputs[]` and flow-level `dataSpace` described under "Fill the required inputs" below.*
+
+## Fill the required inputs — start inputs + data space
+
+An Automation Event start SAVES even when incomplete, but the saved flow comes back **`InvalidDraft`** (cannot be activated) unless it ALSO supplies the fields below. **Saving is not validating** — emit all of these on the first save so the generated flow is activatable, not merely persistable. Discovery (describe) tells you WHICH inputs the event requires; the notes here tell you what VALUES to put in them and add the one field discovery can't surface (`dataSpace`).
+
+| Field | Where | Required for | Value |
+|---|---|---|---|
+| `associatedContent` | start **input parameter** (STRING) | all email-engagement events | Id of the Managed Content whose engagement is monitored (the email/message content) |
+| `specificLink` | start **input parameter** (STRING) | **email link click only** | the link to watch, or `"ANY"` to match any link |
+| `dataSpace` | **flow-level** field (NOT a start input, so it does NOT appear in describe) | all email-engagement events | a Data Space developer name that resolves on the org (commonly `"default"`) |
+
+**Populate start `inputs[]` here — the one AutoLaunched exception.** AutomationEvent engagement flows are AutoLaunched, yet they REQUIRE start input parameters; do NOT drop them under the general "no start inputs on AutoLaunched flows" guidance. The shape is the standard start `inputs[]` (`name` + `value`), same as a PlatformEvent start:
+
+```json
+"start": {
+  "triggerType": "AutomationEvent",
+  "eventName": "trgrOnEmailLinkClickEngagement",
+  "eventType": "trgrOnEmailLinkClickEngagement",
+  "inputs": [
+    { "name": "associatedContent", "value": { "stringValue": "<Managed Content Id>" } },
+    { "name": "specificLink", "value": { "stringValue": "ANY" } }
+  ],
+  "connector": { "targetReference": "<first element>", "isGoTo": false }
+}
+```
+
+The data space is a **flow-root** field, not a start field, and is NOT one of the event's discoverable inputs — set it yourself:
+
+```json
+{ "processType": "AutoLaunchedFlow", "dataSpace": "default", "start": { "...": "..." } }
+```
+
+- **`associatedContent`** is required for all email-engagement events; its value is a Managed Content record Id that exists on the org.
+- **`specificLink`** is required ONLY for the email link-click event; the other events do not take it. Use `"ANY"` to fire on any link.
+- **`dataSpace`** must resolve to a Data Space on the target org (`"default"` is the common value). Set it on the first save — omitting it blocks activation with `DATA_SPACE_REQUIRED_FOR_FLOW_TYPE`.
+- These require an engagement/content-provisioned org (see the provisioning note above): the Managed Content record and the Data Space must actually exist, or the flow saves as `InvalidDraft` (missing content) or fails to save at all (no Data Space backend).
+- **No fault paths unless asked.** An `AutomationEvent` flow is a marketing flow: add a `faultConnector` or error-handling branch only when the user asks for error handling. A bounce event is an engagement trigger, not a request for error handling. See `../../shared/fault-paths/fault-paths.md` § Marketing Flows — Fault Paths Only When Asked.
+
+## Special treatment — what discovery does NOT tell you
+
+Discovery gives you the event's trigger string and its required inputs. These few things it does not surface, so they stay called out here:
+
+- **Version floors (functional prerequisite):** email open / link click / bounce require API version 254+; response requires 260+. If the flow's API version is below the floor for the chosen event, that event is unavailable — describe won't flag this, so check the flow's API version.
+- **`associatedContent` value differs by surface:** on an Automation Event *start* (this guide) it is a Managed Content Id passed as a `stringValue` (see the snippet above); on a *mid-flow* Wait Until Event it is an element reference — see `../wait/wait.md`. Do not carry one shape into the other.
+
+For reference, the OOTB core email-engagement events you will typically see returned by `GET /services/data/vXX.0/flowbuilder/action/invocable-events` (discovery is authoritative — always use the exact string it returns):
+
+| User intent | trigger string |
+|---|---|
+| Email is **opened** | `trgrOnEmailOpenEngagement` |
+| A **link** in the email is **clicked** | `trgrOnEmailLinkClickEngagement` (the "Link" variant — not `trgrOnEmailClickEngagement`) |
+| Email **bounces** | `trgrOnEmailBounceEngagement` |
+| Recipient **responds** to the email | `trgrOnEmailResponseEngagement` |
+
+## Out of scope — MCE email click (STOP and ask)
+
+`trgrOnMceEmailClickEngagement` (Marketing Cloud Engagement email link click) is NOT part of the OOTB core-email flavor. It requires MCE provisioning and pairs only with a `SEND_TO_MCE_EMAIL` send, never the core Send Email. If the user asks for an MCE email-engagement trigger, STOP and confirm the org has MCE provisioning before proceeding — do NOT emit `trgrOnMceEmailClickEngagement` on a core-email flow.