@salesforce/afv-skills 1.54.0 → 1.56.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/afv-skills",
-  "version": "1.54.0",
+  "version": "1.56.0",
   "description": "Salesforce skills for Agentforce Vibes",
   "license": "CC-BY-NC-4.0",
   "files": [

package/skills/agentforce-generate/SKILL.md

@@ -327,6 +327,14 @@ change. Never invent unavailable action inputs, outputs, or model reasoning.
 3. Present the exact target org and version state. Obtain explicit user approval
    before publishing or activating.
 4. Publish, activate, and verify the user-facing agent only after approval.
+5. **Voice agents — wiring a telephony channel is a separate, opt-in step; never
+   auto-wire it.** Attaching a phone number creates real routing infrastructure
+   (flows, a queue, an active `MessagingChannel`) and consumes a provisioned
+   number, so do it only when the user **explicitly asks** and has supplied a
+   **provisioned phone number** (confirm it exists — do not assume or invent
+   one). If either is missing, stop and say what's needed. When both hold, attach
+   it headless via the CLI — do not send the user to Agent Builder. Follow
+   [Headless Telephony CLI](references/voice-telephony-cli.md).
 
 ### Delete or Rename an Agent
 

package/skills/agentforce-generate/references/actions-reference.md

@@ -560,9 +560,9 @@ connection messaging:
 |---------|-------------|----------|
 | `messaging` | Chat/messaging channels; also the escalation-routing surface | Enhanced Chat, Web Chat, In-App; human escalation via `@utils.escalate` |
 | `customer_web_client` | Enhanced Chat v2 (ECv2) surface — the voice-capable connection ADLC authors | Voice agents, Agent Builder Preview (see [Voice Modality Reference](voice-modality-reference.md)) |
-| `telephony` | Voice/phone routing channel | Service Cloud Voice, phone support (channel attachment is UI-only) |
+| `telephony` | Voice/phone routing channel | Service Cloud Voice, phone support (channel attachment is headless via CLI — see [voice-telephony-cli.md](voice-telephony-cli.md)) |
 
-> **Voice agents** use `connection customer_web_client:` (ECv2) as the authored voice surface. `telephony` (Service Cloud Voice) is a real channel, but attaching a phone number / SIP endpoint is a UI-only step — see the voice reference. Do **not** author a `connection voice:` block; it does not exist.
+> **Voice agents** use `connection customer_web_client:` (ECv2) as the authored voice surface. `telephony` (Service Cloud Voice) is a real channel, and attaching a phone number is done **headless via the CLI** ([voice-telephony-cli.md](voice-telephony-cli.md)) — not a UI-only step. Do **not** author a `connection voice:` block; it does not exist.
 
 **CRITICAL**: Values like `"queue"`, `"skill"`, `"agent"` for `outbound_route_type` cause validation errors!
 

package/skills/agentforce-generate/references/voice-modality-reference.md

@@ -138,14 +138,31 @@ Supported pronunciation types: `IPA` (International Phonetic Alphabet), `CMU` (C
 Voice interactions differ from text. When authoring instructions for voice agents:
 
 1. **Keep responses concise.** Users cannot scan/skim voice responses. Aim for 1-2 sentences per turn, not paragraphs. (Long turns also risk tripping the silence/nudge timer — see [voice-latency-heuristics.md](voice-latency-heuristics.md) §5.)
-2. **Avoid lists longer than 3 items.** Users lose track of spoken lists. Offer to repeat or narrow down.
-3. **Use confirmation patterns.** Repeat back key information (account numbers, dates, amounts) before taking action.
+2. **Avoid lists longer than 3 items — and batch long ones.** Users lose track of spoken lists. For a list that can be long, read at most **2 items per turn** and offer to continue (*"Would you like the next two?"*) rather than reading the whole set. **Never speak a raw total count** ("I found forty-seven results") — it's meaningless aloud; summarize or offer to narrow instead.
+3. **Use confirmation patterns — and split capture from action.** Repeat back key information (account numbers, dates, amounts) before taking action. For anything that triggers an irreversible action (sending an email/SMS, creating a record), make **capture and send two separate steps**: capture and store the value, read it back, get a yes, and only *then* call the action that acts on it. Don't let a single turn both collect a misheard value and act on it.
 4. **Design for barge-in.** Users may interrupt. Instructions should handle partial inputs gracefully. Add: *"If the caller starts talking, stop speaking immediately, listen, and respond to what they said — don't finish your sentence."*
 5. **Avoid formatting references.** Do not reference links, bullet points, tables, or visual formatting in instructions — they don't render in voice.
-6. **Acknowledge slow actions with a filler phrase.** Before calling any action that takes more than ~800ms (SOQL, external HTTP, retrieval), have the agent say a short filler so the caller knows it's working. Rotate a few: *"One moment", "Let me pull that up", "Checking now"*. For a known-slow action, be specific: *"When calling `LookupAccountHistory`, say 'This can take a few seconds — hang with me.'"* This is the instruction-level fix for the latency patterns in [voice-latency-heuristics.md](voice-latency-heuristics.md).
-7. **Render numbers, prices, and IDs in spoken form.** TTS reads `$19.99` and `+14155551212` as garble. Instruct: *"When reading numbers, prices, phone numbers, IDs, or dates, use natural spoken form — never read punctuation, currency symbols, or raw digits."* Spell out numbers under 100 ("twenty-five"); prices as *"nineteen dollars and ninety-nine cents"*; phone numbers digit-by-digit grouped naturally; dates as *"May tenth, twenty twenty-six"*.
+6. **Acknowledge slow actions — prefer the platform's progress indicator over LLM filler.** Any action over ~800ms (SOQL, external HTTP, retrieval) needs a "still working" signal. **Best practice:** set a `progress_indicator_message` on the action itself (*"Just a moment while I look that up"*) so the platform speaks the hold phrase and the agent's own turn begins **with the answer** — don't have the LLM vocalize "one moment" as well, or the caller hears it twice. Reserve LLM-spoken filler (*"Let me pull that up"*) for cases where you can't set a progress message. Mark truly instant actions out of the progress indicator so they don't announce a delay that isn't there. This is the instruction-level fix for the latency patterns in [voice-latency-heuristics.md](voice-latency-heuristics.md).
+7. **Render numbers, prices, and IDs in spoken form.** TTS reads `$19.99` and `+14155551212` as garble. Instruct: *"When reading numbers, prices, phone numbers, IDs, or dates, use natural spoken form — never read punctuation, currency symbols, or raw digits."* Spell out numbers under 100 ("twenty-five"); prices as *"nineteen dollars and ninety-nine cents"*; phone numbers digit-by-digit grouped naturally; dates as *"May tenth, twenty twenty-six"*. Author this guidance **once** — do not stack extra rules or tag overrides trying to force phone-number grouping, country-code suppression, or a specific date format. Those are platform-controlled; see "Entity Confirmation & Normalization" below.
 8. **Add ASR repair prompts for misheard input.** Speech recognition isn't perfect. Instruct: *"If the caller's response doesn't match an expected value, or you're unsure what you heard, repeat it back and ask them to confirm — e.g. 'I heard four four two, is that right?'"*
 9. **Give empty results a caller-friendly fallback.** Any lookup that can return zero results needs a graceful recovery. Instruct: *"If a lookup returns nothing, don't say 'no records found.' Say something like 'I couldn't find that account — could you spell your last name?' or offer a different search."* (Pair with voice-friendly action error shapes — see [actions-reference.md](actions-reference.md) "Voice-Safe Action Authoring".)
+10. **Never claim an action happened unless it did.** The most common voice failure mode is the agent saying *"I've sent that to you"* or *"you'll get a text shortly"* when no action actually fired. Instruct explicitly: *"Never state or imply that an email, SMS, or record action has happened, is happening, or will happen unless you actually executed the corresponding action this turn."* Confirm delivery only *after* the action returns success.
+11. **Never expose internals to the caller.** Action names, variable names, JSON, tool inputs, and retriever/knowledge-source names must never be spoken aloud. Instruct: *"When invoking an action, say only the configured progress message or the final customer-facing answer — never read out action names, field names, or raw data structures."*
+
+### Entity Confirmation & Normalization — what you CANNOT control from instructions
+
+How spoken entities are **read back and confirmed** (phone numbers, currency, dates, numerals, IDs) is decided by the platform's voice normalization layer, **downstream of your agent instructions**. A few specific behaviors are **not** reliably controllable from the `.agent` file — and trying to control them makes things *worse*, not better:
+
+- **Country code on phone numbers** (e.g. a "plus one" prepended to a US number). Whether it appears is decided by the normalization layer, not your prompt.
+- **Digit grouping when reading numbers back** (e.g. `980 23 222 45` vs. an even digit-by-digit read). Grouping is applied at the language level and can vary run-to-run.
+- **Dropping the current year from a date** (e.g. reading a same-year date as month and day only).
+
+**Do NOT author custom instructions or tag overrides to fight these.** Adding rules like "always emit the phone tag with an empty country code," "read phone numbers as area-code / prefix / last-four," or "always include the year" **conflicts with the platform's built-in tagging and makes readback *less* consistent, not more.** In practice these overrides produce unreliable, ~50/50 results and can destabilize otherwise-correct normalization.
+
+**What to do instead:**
+- Write the spoken-form guidance in item 7 **once**, and stop there. Tag entities correctly (say the value is a phone number, a price, a date) and let the platform normalize it.
+- If a customer needs a specific readback format or wants to **suppress an out-of-the-box confirmation**, that is **platform/product configuration, not agent-script authoring**. Per-entity confirmation configurability is active platform work — surface the requirement to the voice product team rather than encoding a workaround in the `.agent` file.
+- Set the customer's expectations: these three behaviors may still occur regardless of instructions, and are being addressed at the platform layer.
 
 ### Instruction Example — Voice vs Text
 
@@ -184,7 +201,7 @@ connection customer_web_client:
     adaptive_response_allowed: True
 ```
 
-> **Choosing a surface — ECv2 (`customer_web_client`) vs Telephony.** Both ECv2 and Telephony (Service Cloud Voice) are voice-capable channels. In Agent Builder, adding *either* connection auto-enables Voice Settings. ADLC authors **`customer_web_client` (ECv2)** because it is the surface that is reliably created via the CLI/DSL today and is what Agent Builder Preview requires; Telephony/SCV channel attachment (phone number / SIP) is a UI-only step (see "Known Limitation" below). If your deployment target is Service Cloud Voice telephony, author `customer_web_client` for authoring/preview and complete the telephony channel wiring in the UI.
+> **Choosing a surface — ECv2 (`customer_web_client`) vs Telephony.** Both ECv2 and Telephony (Service Cloud Voice) are voice-capable channels. In Agent Builder, adding *either* connection auto-enables Voice Settings. ADLC authors **`customer_web_client` (ECv2)** because it is the surface that is reliably created via the CLI/DSL today and is what Agent Builder Preview requires. If your deployment target is Service Cloud Voice telephony, author `customer_web_client` for authoring/preview, then complete the telephony channel wiring **headless via the CLI** — see [voice-telephony-cli.md](voice-telephony-cli.md) (`MessagingChannel` + routing flow + `Atlas__VoiceAgent` planner). It is *not* a UI-only step.
 >
 > **Do not** invent `connection voice:`, and do not remove an existing `connection messaging:` block when enabling voice — enabling voice **adds** the `modality voice:` block, the `VoiceCallId` variable, and `connection customer_web_client:`.
 
@@ -207,24 +224,43 @@ The `modality voice:` block is validated during `sf agent validate`. Common issu
 - Out-of-range floats — `outbound_speed` must be 0.5–2.0, others must be 0.0–1.0
 - Timing values out of bounds — speak-up timers: 10s–5min, endpointing/beepboop: 0.5s–60s
 
-## Known Limitation — Voice-Channel Deploy Is UI-Only
-
-You can **author** and **validate** a voice bundle entirely headless (CLI/API): `sf agent validate authoring-bundle` and `sf agent publish authoring-bundle` compile and deploy the agent metadata, including the `modality voice:` block. What the CLI **cannot** do today is wire the published agent to the actual telephony/voice channel — that last-mile connection step is only available in the Agent Builder UI.
-
-After publishing, the user must open the agent in **Agent Builder → Connections → Voice** and click **Continue** to:
-1. Attach the agent to a voice channel (phone number / SIP endpoint), and
-2. Optionally customize the voice and tuning (see "Default Voice — start here" above).
-
-This is the one break in an otherwise headless flow. It is a tracked Project Codey "Steel Thread 2" gap (deploy-to-voice-channel not supported in CLI) — surface it to the user rather than implying `sf agent publish` fully activates the voice channel. Until CLI support lands, treat the UI step as a required manual handoff and tell the user exactly which screen to open.
+## Telephony Channel Setup Is Headless (CLI) — No UI Step Required
+
+You can **author**, **validate**, **publish**, AND **wire to a telephony channel** entirely
+headless (CLI/API). `sf agent validate/publish authoring-bundle` compile and deploy the agent
+metadata (including the `modality voice:` block); the last-mile telephony/voice channel
+attachment — creating the `MessagingChannel`, wiring the routing flow, and going Live on a
+phone number — is done with `sf data create record`, `sf project deploy`, and `sf api request
+rest`. See **[voice-telephony-cli.md](voice-telephony-cli.md)** for the full procedure.
+
+> **Correction to prior guidance.** Earlier versions of this doc treated voice-channel deploy as
+> UI-only (open Agent Builder → Connections → Voice → Continue). That is **no longer accurate** —
+> the same channel wiring is fully scriptable via the CLI (proven by the Contact Center
+> `afv-pstn-setup-cli` skill: "fully headless, no browser"). Do **not** tell the user the channel
+> step requires the UI.
+
+The **one** thing that still needs the UI is picking a **non-default voice ID / tuning** — the
+voice picklist (names, gender, accent, locale) is not enumerable via CLI, so ADLC authors the
+platform default voice and the user customizes later in Agent Builder → Connections → Voice
+(see "Default Voice — start here" above). This is a voice-*selection* limitation, not a
+channel-*attachment* one.
+
+Headless telephony wiring, in brief (full detail + gotchas in
+[voice-telephony-cli.md](voice-telephony-cli.md)):
+1. Planner: `plannerType=Atlas__VoiceAgent` + a `SurfaceAction__Telephony` plannerSurface, with ≥1 topic.
+2. Deploy escalation flow → voice queue (`RoutingModel=ExternalRouting`) → inbound routing flow (`routingType=Copilot`).
+3. `MessagingChannel` (`MessageType=PstnVoice`, `MessagingPlatformKey=<phone>`), then PATCH `SessionHandlerId` (FlowDefinition `300…`) + `FallbackQueueId`.
+4. Poll the phone number to `CodeStatus=Live`; smoke-test with a call.
 
 ## Steel Thread Alignment (Project Codey)
 
 Voice work in ADLC targets **Steel Thread 2 — "Voice-Enabled Agent with Knowledge Grounding"**: build voice agents with subagents, actions, and knowledge integration (ADL / Salesforce Knowledge), then deploy to the voice channel. Two implications for authoring:
 
 - **Pair voice with knowledge grounding.** Voice service agents are almost always FAQ/policy-backed, so `/agentforce-generate` proactively asks the Knowledge Grounding question when it detects a voice agent. The combined template is `assets/agents/voice-knowledge-grounded.agent`.
-- **Deploy is the known gap.** See "Known Limitation" above — authoring and validation are headless; channel wiring is UI-only.
+- **Deploy is now fully headless.** Authoring, validation, publish, AND telephony-channel wiring are all CLI — see [voice-telephony-cli.md](voice-telephony-cli.md). (Formerly a Steel Thread 2 gap; the channel step no longer requires the UI. Only non-default voice-ID selection remains UI-only.)
 
 ## Related References
 
+- [voice-telephony-cli.md](voice-telephony-cli.md) — headless PSTN/telephony channel setup via SF CLI (MessagingChannel, routing flows, `Atlas__VoiceAgent` planner, troubleshooting).
 - [voice-latency-heuristics.md](voice-latency-heuristics.md) — latency anti-patterns (sync writes, bulky retrieval, long turns) for authoring and trace diagnosis.
 - [actions-reference.md](actions-reference.md) "Voice-Safe Action Authoring" — voice-safe action descriptions, parameter names, enums, error shapes.

package/skills/agentforce-generate/references/voice-telephony-cli.md

@@ -0,0 +1,193 @@
+# Headless Telephony (PSTN) Channel Attach via SF CLI
+
+**Scope: the last step only.** This covers attaching an **already-authored, published, and
+active** voice agent to a real phone number (PSTN) — the step this skill previously deferred to
+the Agent Builder UI. Authoring the agent (the `.agent` file, `modality voice:` block,
+subagents/topics/actions, publish, activate) is handled by the normal `agentforce-generate`
+flow — **do not re-do it here.** This doc starts *after* `sf agent publish` + `sf agent activate`.
+
+The whole channel attach is headless — `sf` CLI, `sf project deploy`, and REST. **No Agent
+Builder step.** This supersedes the older "channel wiring is UI-only" guidance.
+
+> **Ask before wiring — this step is opt-in.** Channel attach creates real routing
+> infrastructure (flows, a queue, an active `MessagingChannel`) and binds a provisioned phone
+> number. **Never run it automatically** as part of publish/activate. Confirm both first:
+> (1) the user has **explicitly asked** to wire telephony, and (2) a **provisioned phone number**
+> exists (do not assume/invent one). If either is missing, stop and tell the user what's needed.
+
+> The only thing that still needs the UI is picking a **non-default voice ID / tuning** (the
+> voice picklist isn't enumerable via CLI — see [voice-modality-reference.md](voice-modality-reference.md)).
+> Channel *attachment* is not UI-only.
+
+Commands below are adapted from the Agentforce Contact Center `afv-pstn-setup-cli` skill.
+
+---
+
+## Prerequisites (produced by the normal authoring flow)
+
+- A voice agent **already published + active** via `agentforce-generate` (authored with
+  `modality voice:` and a voice-capable connection surface).
+- Org authenticated via `sf` CLI; you are inside the SFDX project dir (`sf agent
+  activate/deactivate` fail outside one with `InvalidProjectWorkspaceError`).
+- A **provisioned phone number** supplied by the user (do not assume one).
+
+---
+
+## What "attach to telephony" adds on top of the published agent
+
+```text
+Inbound call on +1XXXXXXXXXX
+        ↓  MessagingChannel (PstnVoice)  ← created here
+  SessionHandlerId → FlowDefinition (300…)
+        ↓  Voice Routing Flow (routingType=Copilot)  ← created here
+  copilotId → BotDefinition (the published agent)
+        ↓
+  Published voice agent (planner needs a Telephony surface — see Step 1)
+        ↓ (on escalation)
+  Voice Escalation Flow (routingType=QueueBased) → voice queue  ← created here
+```
+
+Deploy order: **preflight number is Live (Step 0) → escalation flow → queue → (verify planner) → inbound routing flow → channel.**
+
+---
+
+## Step 0 — Preflight: the supplied number must already be provisioned + Live (do this FIRST)
+
+**Before any deploy or create step**, confirm the exact phone number the user supplied is
+already provisioned and `CodeStatus=Live`. Nothing below (planner patch, escalation flow, queue,
+inbound flow, `MessagingChannel`) may run until this passes — otherwise a typo'd or unprovisioned
+number leaves real routing infrastructure created for a number that can never route, which defeats
+the opt-in gate.
+
+```bash
+sf data query --target-org <alias> \
+  --query "SELECT Id, CodeStatus FROM PhoneNumber WHERE PhoneNumber='<phone_number>'"
+```
+Proceed **only** when the query returns exactly the supplied number with `CodeStatus=Live`. **Stop
+and make zero changes** if any of these hold:
+- no row is returned (number not provisioned on this org),
+- `CodeStatus` is anything other than `Live` (still provisioning / failed),
+- the query errors with `INVALID_TYPE` (Agentforce Voice numbers aren't provisioned on this org —
+  verify in Setup → Service → Voice → Agentforce Voice Setup).
+
+Tell the user exactly what's missing and do not attempt to create or invent a number.
+
+## Step 1 — Verify the published planner carries a Telephony surface
+
+Authoring produces the planner; you only need to **confirm** (and patch only if missing) that it
+has a `Telephony` surface — the DSL commonly emits `Messaging` + `CustomerWebClient` (ECv2 for
+Preview) but PSTN routing needs `SurfaceAction__Telephony`.
+
+```bash
+sf project retrieve start --metadata "GenAiPlannerBundle:<Agent_API_Name>" --target-org <alias>
+```
+Confirm: `plannerType=Atlas__VoiceAgent`, a `SurfaceAction__Telephony` `plannerSurface`
+(with `outboundRouteConfigs` naming the escalation flow), and ≥1 `localTopics` (a topic-less
+planner accepts then drops calls in ~10s). If the Telephony surface is absent, add it and
+redeploy with the agent deactivated:
+```bash
+sf agent deactivate --api-name <Agent_API_Name> --target-org <alias>
+sf project deploy start --source-dir <project-source-dir>/genAiPlannerBundles/<Agent_API_Name> --target-org <alias> --wait 10
+sf agent activate --api-name <Agent_API_Name> --target-org <alias>
+```
+> `<project-source-dir>` is the source directory derived from `sfdx-project.json`: take the
+> `packageDirectories[]` entry with `"default": true` (else the first) and append `/main/default`
+> to its `path` → e.g. `force-app/main/default`. The `path` value alone (e.g. `force-app`) is the
+> package root, not the source dir — don't append the metadata folder to it directly.
+> Topics/actions themselves come from the authored `.agent` — don't hand-write them here; if
+> they're missing, fix the source agent and re-publish via `agentforce-generate`.
+
+## Step 2 — Voice queue (ExternalRouting)
+
+Deploy `QueueRoutingConfig` with **`RoutingModel=ExternalRouting`** (`LeastActive` breaks PSTN —
+calls arrive, agent never answers), a `Group` (Queue) linked to it, a `QueueSObject` for
+`VoiceCall`, and add the running user as a member. Save the queue Id.
+
+## Step 3 — Escalation flow (before Step 4/5)
+
+Deploy a `RoutingFlow`: `routingType=QueueBased`, `serviceChannelDevName=sfdc_phone`, variable
+`recordId` (capital I), `apiVersion=66.0`. The planner references `<Agent_API_Name>_Voice_Escalation`
+by name — a missing flow silently breaks escalation.
+
+## Step 4 — Inbound voice routing flow
+
+Deploy a `RoutingFlow` that routes inbound calls to the agent. Critical fields (from a working org):
+- `routingType` = **`Copilot`** (NOT `Bot` — silently fails)
+- `copilotId.setupReferenceType` = **`BotDefinition`** (NOT `Bot`)
+- `serviceChannelLabel` = **`Phone`** (NOT `"Voice Call"`); `serviceChannelDevName` = `sfdc_phone`
+- Variable name = **`recordid`** (lowercase — differs from the escalation flow's `recordId`)
+- Include **all** empty `<inputParameters>` Flow Builder generates; `apiVersion=66.0`,
+  `CanvasMode=AUTO_LAYOUT_CANVAS`, `areMetricsLoggedToDataCloud=false`
+
+## Step 5 — Create + wire the MessagingChannel (the former "UI-only" step)
+
+This is the core of the last step — what Agent Builder → Connections → Voice used to own:
+
+```bash
+# 1. Create the channel
+CHANNEL_ID=$(sf data create record --sobject MessagingChannel \
+  --values "MasterLabel='<Label>' DeveloperName='<Dev_Name>' MessageType='PstnVoice' MessagingPlatformKey='<phone_number>' IsActive=true" \
+  --json --target-org <alias> | python3 -c "import json,sys;print(json.load(sys.stdin)['result']['id'])")
+
+# 2. Get the inbound flow's FlowDefinition ID (300… prefix — NOT the 301… version ID)
+FLOW_DEF_ID=$(sf api request rest \
+  "/services/data/v62.0/tooling/query?q=SELECT+Id+FROM+FlowDefinition+WHERE+DeveloperName='<Agent_API_Name>_Voice_Omni_Flow'" \
+  --target-org <alias> | python3 -c "import json,sys;r=json.load(sys.stdin)['records'];print(r[0]['Id'] if r else '')")
+
+# 3. Wire SessionHandlerId + FallbackQueueId (both mandatory)
+sf api request rest "/services/data/v62.0/sobjects/MessagingChannel/$CHANNEL_ID" \
+  --method PATCH \
+  --body "{\"SessionHandlerId\":\"$FLOW_DEF_ID\",\"FallbackQueueId\":\"<Queue_Id>\"}" \
+  --target-org <alias>
+```
+
+Channel facts:
+- `MessageType` = **`PstnVoice`** (NOT `Phone` — only one `Phone` channel allowed per org).
+- `SessionHandlerId` must be a **FlowDefinition ID (`300…`)**, not a Flow *version* ID (`301…`).
+- `FallbackQueueId` is **mandatory** — without it calls may drop.
+
+## Step 6 — Smoke-test end-to-end
+
+The number was already confirmed `Live` in Step 0, so this step just verifies the wiring holds
+together: agent `Status=Active`, channel `IsActive=true` with `SessionHandlerId` set, phone still
+`CodeStatus=Live`, queue has a `VoiceCall` SObject + ≥1 member.
+```bash
+sf data query --query "SELECT Id, CodeStatus FROM PhoneNumber WHERE PhoneNumber='<phone_number>'" --target-org <alias>
+```
+Then place a test call and confirm the agent answers.
+
+---
+
+## Troubleshooting — call not reaching the agent
+
+```bash
+sf data query --query "SELECT Id, DisconnectReason, ConversationId, CallSubtype, VendorType FROM VoiceCall ORDER BY CreatedDate DESC LIMIT 5" --target-org <alias>
+sf data query --query "SELECT Id, BotId, Status, ActiveTime, HandleTime, RoutingModel FROM AgentWork ORDER BY CreatedDate DESC LIMIT 5" --target-org <alias>
+```
+
+| VoiceCall.ConversationId | AgentWork | ActiveTime | Root cause |
+|---|---|---|---|
+| null | — | — | PSTN / Amazon Connect not reaching Salesforce |
+| set | none | — | Routing flow not running, or `SessionHandlerId` is a `301…` version ID |
+| set | BotId null | — | Queue `RoutingModel=LeastActive` → change to `ExternalRouting` |
+| set | BotId set | 0 | Planner has **no topics** — fix source agent, re-publish |
+| set | BotId set | >0 | Bot ran — inspect `MessagingSession` + transcript / welcome message |
+
+## Key gotchas (channel-attach only)
+
+| Mistake | Symptom | Fix |
+|---|---|---|
+| `routingType=Bot` in inbound flow | Agent not invoked | `routingType=Copilot` |
+| `setupReferenceType=Bot` | Deploy error / silent fail | `BotDefinition` |
+| `serviceChannelLabel="Voice Call"` | Flow can't resolve channel | `"Phone"` |
+| No `SurfaceAction__Telephony` surface on planner | Escalation never fires on voice | Add Telephony surface + redeploy (Step 1) |
+| `SessionHandlerId` = `301…` (version) | Channel doesn't route | Use FlowDefinition `300…` |
+| `MessageType=Phone` | "Only one Phone channel allowed" | `PstnVoice` |
+| `RoutingModel=LeastActive` | Calls arrive, agent never answers | `ExternalRouting` |
+| `sf agent activate/deactivate` outside project dir | `InvalidProjectWorkspaceError` | `cd` into the SFDX project first |
+
+---
+
+## Related References
+- [voice-modality-reference.md](voice-modality-reference.md) — `modality voice:` block, connection surfaces, authoring guidance.
+- [voice-latency-heuristics.md](voice-latency-heuristics.md) — live-call latency anti-patterns.

package/skills/agentforce-observe/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agentforce-observe
-description: "Analyze production Agentforce agent behavior using session traces and Data Cloud, and manage Agent Health Monitoring (AHM) alerts. TRIGGER when: user queries STDM session data or Data Cloud trace records; investigates production agent failures, regressions, or performance issues; asks about session traces, conversation logs, or agent metrics; wants to reproduce a reported production issue in preview; runs findSessions or trace analysis queries; creates, lists, or deletes an AHM data alert on an agent metric (escalation rate, deflection, etc.); asks why an alert is not firing or wants to check whether alerts have fired (notification counts, or the per-alert Incidents view). DO NOT TRIGGER when: user creates, modifies, or debugs .agent files during development (use agentforce-generate); writes or runs test specs (use agentforce-test); uses sf agent preview for local development iteration; deploys or publishes agents."
+description: "Analyze production Agentforce agent behavior using session traces and Data Cloud, and manage Agent Health Monitoring (AHM) alerts. TRIGGER when: user queries STDM session data or Data Cloud trace records; investigates production agent failures, regressions, or performance issues; asks about session traces, conversation logs, or agent metrics; wants to reproduce a reported production issue in preview; runs findSessions or trace analysis queries; creates, lists, updates, or deletes an AHM data alert on an agent metric (escalation rate, deflection, etc.); asks why an alert is not firing or wants to check whether alerts have fired (notification counts, or the per-alert Incidents view). DO NOT TRIGGER when: user creates, modifies, or debugs .agent files during development (use agentforce-generate); writes or runs test specs (use agentforce-test); uses sf agent preview for local development iteration; deploys or publishes agents."
 allowed-tools: Bash Read Write Edit Glob Grep
 metadata:
   relatedSkills:
@@ -57,9 +57,9 @@ Determine intent from user input:
 - **"analyze" / "sessions" / "what's wrong"** -> Phase 1 only, then suggest next steps
 - **"reproduce" / "test" / "preview"** -> Phase 2 (run Phase 1 first if no issues in hand)
 - **"fix" / "improve" / "update"** -> Phase 3 (run Phase 1 first if no issues in hand)
-- **"create alert" / "set up monitoring" / "alert me when"** -> Phase 4 (create)
-- **"list alerts" / "show my alerts" / "delete alert"** -> Phase 4 (list / delete)
-- **"why isn't my alert firing" / "have my alerts fired" / "alert notifications"** -> Phase 4 (notification-count signal + Incidents view + metric verify)
+- **"create alert" / "set up monitoring" / "alert me when"** -> AHM (create)
+- **"list alerts" / "show my alerts" / "update alert" / "delete alert"** -> AHM (list / update via PUT / delete)
+- **"get / list notifications" / "notifications for a specific alert" / "have my alerts fired" / "why isn't my alert firing"** -> AHM: fetch notifications with header `X-UNS-Type-Filter: all`, report status + list; for a specific alert, filter by alertId from `targetPageRef.state.c__alertId` (15/18-char-safe), not metricId (+ Incidents view + metric verify)
 
 ### Resolve agent name
 
@@ -394,16 +394,20 @@ Proactive complement to the reactive Observe phases: **AHM data alerts** fire wh
 # List/describe -- resolve owner id first (required); single-alert GET is 405 => list + filter client-side
 USER_ID=$(sf org display user --target-org <org> --json | python3 -c 'import sys,json;print(json.load(sys.stdin)["result"]["id"])')
 sf api request rest "/services/data/v66.0/tableau/dataAlerts?ownerId=$USER_ID" -o <org>
-# Create (body built per reference into a 0600 mktemp file) / delete (204)
+# Create / PUT update-in-place / delete (204). PUT & DELETE are addressed by $ALERT_ID in the path; PUT takes the full POST-style body. Bodies per reference into a 0600 mktemp file.
 sf api request rest "/services/data/v66.0/tableau/dataAlerts" -X POST -H "Content-Type: application/json" -b "@$body" -o <org>
+sf api request rest "/services/data/v66.0/tableau/dataAlerts/$ALERT_ID" -X PUT -H "Content-Type: application/json" -b "@$body" -o <org>
 sf api request rest "/services/data/v66.0/tableau/dataAlerts/$ALERT_ID" -X DELETE -o <org> --include
-# Notification counts are org-global, NOT per-alert (confirm the specific alert in the UI Incidents tab).
-sf api request rest "/services/data/v66.0/connect/notifications/status" -o <org>
+# Notifications REQUIRE header X-UNS-Type-Filter: all (else custom-types-only => AHM empty = false 0). Report status + list.
+sf api request rest "/services/data/v66.0/connect/notifications/status" -H "X-UNS-Type-Filter: all" -o <org>
+sf api request rest "/services/data/v66.0/connect/notifications"        -H "X-UNS-Type-Filter: all" -o <org>
+# AHM notifications: type=templatized_data_alert; no per-alert endpoint. Attribute by alertId in targetPageRef.state.c__alertId (15/18-char-safe), NOT metricId (collides).
 ```
 
-**Two silent-failure traps to carry into any alert work:**
+**Three silent-failure traps to carry into any alert work:**
 - **Thresholds are raw 0-1 ratios**, not display percentages -- 5% is `"0.05"`, `"1"` means 100%.
 - **POST field names/casing differ from GET** -- POST uses `utterance` (not `alertName`) and PascalCase `type` discriminators, so copying a GET response back into a POST fails.
+- **Notifications need `X-UNS-Type-Filter: all`** -- without it `connect/notifications*` returns custom types only, so AHM notifications (type `templatized_data_alert`) come back empty; an empty list is a false negative, not "never fired."
 
 ---
 
@@ -412,7 +416,7 @@ sf api request rest "/services/data/v66.0/connect/notifications/status" -o <org>
 | Reference | Contents |
 |---|---|
 | `references/stdm-queries.md` | STDM query procedures, Apex service deployment, response parsing |
-| `references/ahm-alerts.md` | AHM data-alert create/list/delete, trigger history, SDM/metric/agent discovery, threshold schema, metric verification |
+| `references/ahm-alerts.md` | AHM data-alert create/list/update/delete, trigger history, SDM/metric/agent discovery, threshold schema, metric verification |
 | `references/issue-classification.md` | Issue pattern table, root cause categories, structural analysis checks |
 | `references/reproduce-reference.md` | Phase 2 preview procedures, trace diagnosis, classification criteria |
 | `references/improve-reference.md` | Phase 3 editing, deployment chain, verification, safety, test cases |