@salesforce/afv-skills 1.52.0 → 1.54.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/afv-skills",
-  "version": "1.52.0",
+  "version": "1.54.0",
   "description": "Salesforce skills for Agentforce Vibes",
   "license": "CC-BY-NC-4.0",
   "files": [
@@ -11,8 +11,8 @@
     "registry": "https://registry.npmjs.org"
   },
   "devDependencies": {
-    "@salesforce/ui-bundle-template-app-react-sample-b2e": "^11.57.2",
-    "@salesforce/ui-bundle-template-app-react-sample-b2x": "^11.57.2",
+    "@salesforce/ui-bundle-template-app-react-sample-b2e": "^12.4.4",
+    "@salesforce/ui-bundle-template-app-react-sample-b2x": "^12.4.4",
     "@salesforce/webapp-template-app-react-sample-b2e-experimental": "^1.117.1",
     "@salesforce/webapp-template-app-react-sample-b2x-experimental": "^1.117.1"
   },

package/skills/service-agentforce-contact-center-coordinate/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: service-agentforce-contact-center-coordinate
+description: "Coordinates end-to-end setup of an Agentforce Contact Center voice channel: gathers country and phone-number-type selections, procures a chosen number, resolves its CommunicationChannelLine, verifies the number is live, and creates an active PstnVoice MessagingChannel. The user picks the routing model: Omni Queue (route to the contact center queue) or Omni Flow (route to an Agentforce agent, creating or reusing the agent plus its routing flows). Use when the user asks to set up an Agentforce Contact Center, provision a contact center phone number and voice channel together, or put an Agentforce agent on native voice. TRIGGER when the user says set up agentforce contact center, configure contact center voice, or create a voice channel with omni flow and an agentforce agent. DO NOT TRIGGER when only wiring an existing channel to an existing agent with no number to procure, or creating a non-voice messaging channel."
+allowed-tools: Bash(sf org display:*) Bash(sf org create agent-user:*) Bash(sf data query:*) Bash(sf api request rest:*) Bash(sf agent:*) Bash(sf project deploy start:*) Bash(jq:*) Bash(scripts/*) Bash(./scripts/*) Bash(bash scripts/*) Read AskUserQuestion
+metadata:
+  version: "1.1"
+  minApiVersion: "68.0"
+  domains: ["Service", "Agentforce"]
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+---
+
+# service-agentforce-contact-center-coordinate: Set up an Agentforce Contact Center voice channel
+
+Coordinates the full path from an authenticated org to a live inbound voice channel: procure a phone number, confirm it is provisioned, and create an active `PstnVoice` `MessagingChannel`. The user picks the **routing model** — **Omni Queue** (route calls straight to the Agentforce Contact Center queue) or **Omni Flow** (route to an Agentforce agent via an inbound routing flow, with the queue as fallback). The Omni Queue path only orchestrates the Number Management and MessagingChannel REST APIs. The Omni Flow path can additionally author/publish/activate an Agentforce agent and deploy its inbound (`Copilot`) and escalation (`QueueBased`) `RoutingFlow` flows before wiring the channel.
+
+## Scope
+
+- **In scope**: fetching available numbers, procuring a number, resolving its `CommunicationChannelLine`, verifying/reconciling live status, choosing the routing model, creating and activating a `PstnVoice` `MessagingChannel` (queue- or flow-routed), and — for the Omni Flow path — authoring/publishing/activating an Agentforce agent and deploying its inbound and escalation `RoutingFlow` flows. Ends with a setup summary.
+- **Out of scope**: authenticating or provisioning the org (the target org must already be authenticated), enabling the Agentforce/Einstein Service Agent toggle (an org preference the operator flips — see `references/agentforce-prerequisite.md`), outbound/voice-tuning or wiring a *pre-existing* channel to an agent, and creating non-voice channels.
+
+---
+
+## Prerequisites
+
+- **Authenticated org** — required for every path (this skill never runs an interactive login).
+- **Omni Flow path only — Einstein and Agentforce Agents must be enabled in the org.** Before a voice channel can route to an Agentforce agent, an org admin must turn on **Einstein** (Setup → **Einstein Setup**) and then **Agentforce Agents** (Setup → Einstein → **Agentforce / Agents**) in the Setup UI. The skill then resolves or provisions the canonical **Einstein Agent User** (`Profile.Name = 'Einstein Agent User'`) that agent authoring and publish depend on. Do **not** use generic users whose username/profile merely contains `Agent` or `Bot`; those can generate/validate but fail publish. The **Omni Queue** path has **no** such prerequisite. Full steps: `references/agentforce-prerequisite.md`.
+
+---
+
+## Required Inputs
+
+Gather or confirm before proceeding:
+
+- **Target org**: an already-authenticated org. If the user names an alias, use it. If the user refers to their **default org** (or gives no alias), resolve it with `sf org display --json` and read `result.alias` (falling back to `result.username`); use that value as `<alias>` for every script. Do not run an interactive login.
+- **Country**: `US` or `CA`.
+- **Phone number type**: `10DLC` or `Toll Free`.
+- **Selected number**: chosen by the user from the fetched list.
+- **Routing model**: `Omni Queue` (default) or `Omni Flow`. Asked in Step 7.
+- **(Omni Flow only) Agent source**: create a new Agentforce agent + routing flows, or reuse an existing published agent and its inbound routing flow.
+- **(Omni Flow, new agent only) Agent business context**: agent name, agent description (the agent's role/purpose), and company name — passed to `sf agent generate agent-spec`. The agent name is used as the `<label>`, and the `<apiName>` is derived from it (normalization + uniqueness rule in Step 9 sub-step 3); do not prompt for role, website, or API name.
+
+Do not proceed without an authenticated org and both the country and number-type selections. Collect the routing model and any Omni Flow inputs only if/when that path is chosen.
+
+---
+
+## Workflow
+
+All steps are sequential. If a step fails, stop and report the error rather than continuing.
+
+1. **Confirm the org connection** — run `sf org display --target-org <alias> --json` and read `result.instanceUrl`. If it fails, ask the user to authenticate the org first, then stop. Do not run an interactive login from this skill.
+
+2. **Gather configuration** — use `AskUserQuestion` to collect **Country** (`US`/`CA`) and **Phone Number Type** (`10DLC`/`Toll Free`). Do not mark any option as recommended or default — present the choices neutrally. Wait for both before continuing.
+
+3. **Fetch available numbers** — read `references/number_management_api.md` for the endpoint contract, then run `scripts/fetch-numbers.sh <alias> <country> <phoneType>`. Present the returned numbers as a numbered list and ask the user to select one — do not mark any number as recommended or default.
+
+4. **Procure the selected number** — run `scripts/procure-number.sh <alias> <country> <phoneType> <number>`. On a non-2xx response, map the status via `references/number_management_api.md` and stop with a clear message.
+
+5. **Resolve the ChannelLine** — run `scripts/resolve-channel-line.sh <alias> <number>`. It queries `CommunicationChannelLine` by `Code`, retrying on empty results. Capture the `ChannelLine` Id and `CodeStatus`.
+
+6. **Verify the number is live** — run `scripts/verify-number-live.sh <alias> <number>`. It checks `CodeStatus` via the Tooling API, calls `numberStateReconcile` when not live, and polls per the strategy in `references/verification_and_errors.md`. Branch on the exit code: **exit 3** (still not `Live` after polling) → surface the warning and ask whether to wait or proceed; **exit 4** (`numberStateReconcile` returned a non-2xx) → **stop and report** per the stop-on-non-2xx rule — do not create a channel on top of a failed reconciliation.
+
+7. **Choose the routing model** — use `AskUserQuestion` to ask how calls should route, then branch in Step 9:
+   - **Omni Queue** (default) — route directly to the Agentforce Contact Center queue.
+   - **Omni Flow** — route to an Agentforce agent via an inbound routing flow, with the queue as fallback.
+
+8. **Resolve the contact center queue** — run `scripts/resolve-acc-queue.sh <alias>` to look up the Agentforce Contact Center default queue Id. Never hardcode a queue Id — it is org-specific. Both models need it: Omni Queue uses it as the channel's `SessionHandlerId`; Omni Flow uses it as the `FallbackQueueId` and the escalation-flow target.
+
+9. **Create the active voice channel** — read `references/messaging_channel.md`, then follow the branch for the chosen routing model.
+
+   **Omni Queue** — run `scripts/create-voice-channel.sh <alias> <number> <channelLineId> <queueId>`. This POSTs a `PstnVoice` `MessagingChannel` with `SessionHandlerId` set to the queue, `ChannelLineId` set to the resolved `CommunicationChannelLine` Id, and `IsActive: true`. Handle the field/status errors documented in that reference.
+
+   **Omni Flow** — read `references/omni-flow-routing.md`, then:
+   1. **Prerequisite gate** — run `scripts/check-agentforce-prereq.sh <alias>` (see `references/agentforce-prerequisite.md`). **Exit 0** → capture the printed canonical Einstein Agent User for `--agent-user`; the script reuses an existing `Einstein Agent User` or provisions one with `sf org create agent-user`. **Exit 3** → no canonical user could be found/provisioned, often because the toggle is off or no Agentforce Service Agent User license is available; prompt the user to fix the org and re-run. If the user allows a queue-only fallback, use the Omni Queue create above and note the fallback in the report.
+   2. **New or existing agent** — use `AskUserQuestion`:
+      - **Use existing** — ask for the published agent's API name/label and its inbound `RoutingFlow` DeveloperName, then run `scripts/resolve-flow-definition.sh <alias> <flowDeveloperName>` to get the inbound `FlowDefinition` Id (`300…`). `resolve-flow-definition.sh` verifies only that the *flow* has an active version, not that the agent is published and Active — confirm the agent's latest `BotVersion.Status = 'Active'` (`SELECT Status FROM BotVersion WHERE BotDefinition.DeveloperName = '<apiName>' ORDER BY VersionNumber DESC LIMIT 1`), or tell the user they are responsible for that, before continuing; otherwise the channel is created but calls won't route. Continue at sub-step 5.
+      - **Create new** — continue at sub-step 3.
+   3. **Author the agent** — collect the agent's business context via `AskUserQuestion`: only **agent name**, **agent description** (the agent's role/purpose — this becomes the spec's `--role`), and **company name** (do not prompt for role, website, or API name). Use the agent name as the `<label>`. Derive the `<apiName>` (it becomes the `BotDefinition.DeveloperName` and the routing-flow name base) from the agent name: PascalCase the words, keep only alphanumerics, start with a letter (prefix `A` if needed), cap at 60 chars. Confirm uniqueness via `sf data query --query "SELECT DeveloperName FROM BotDefinition WHERE DeveloperName = '<apiName>'" --target-org <alias>`; append a numeric suffix on a collision. First prepare the SFDX work dir with `scripts/prepare-agent-workdir.sh acc-voice-build`; `sf agent generate agent-spec` requires project context before the authoring-bundle script runs. From inside `acc-voice-build`, generate the spec: `sf agent generate agent-spec --type customer --tone neutral --max-topics 5 --agent-user <einsteinAgentUser> --role "<agent description>" --company-name "<company name>" --output-file specs/<apiName>.yaml --target-org <alias> --json`. Then, from the parent/original work dir, run `scripts/create-voice-agent.sh <alias> <apiName> <label> acc-voice-build/specs/<apiName>.yaml acc-voice-build`, which generates the authoring bundle, fixes the generated `default_agent_user`, deploys the `AiAuthoringBundle`, validates, publishes, and activates the agent. **Do not switch the planner to `Atlas__VoiceAgent`** — keep the publish-generated `Atlas__ConcurrentMultiAgentOrchestration` (deviation note in `references/omni-flow-routing.md`).
+   4. **Deploy the routing flows** — run `scripts/create-routing-flows.sh <alias> <apiName> <label> <queueId> <queueName> acc-voice-build`. It renders and deploys the inbound (`<apiName>_Voice_Omni_Flow`, `Copilot`) and escalation (`<apiName>_Voice_Escalation`, `QueueBased`) flows from inside the prepared SFDX work dir, then prints the inbound `FlowDefinition` Id (`300…`) on stdout — capture it. Reuse the **same** `acc-voice-build` work dir as sub-step 3.
+   5. **Create the channel** — run `scripts/create-voice-channel.sh <alias> <number> <channelLineId> <flowDefinitionId> <queueId>`. The 5th arg switches the POST to Omni Flow: `SessionHandlerId` = the inbound `FlowDefinition` Id, `FallbackQueueId` = the queue.
+
+10. **Confirm setup and write the report** — read the created `MessagingChannel` back. Then write a report using **exactly** the structure in `assets/report-template.md`: fill every field with the real value produced during this run (org alias, country, phone-number type, routing model, the commands actually run, the procured number, the resolved `CommunicationChannelLine` Id and status, the queue resolved **by name** with its Id, and the created `PstnVoice` `MessagingChannel` Id, DeveloperName, ChannelLineId, IsActive, SessionHandlerId, and FallbackQueueId; for Omni Flow also the agent api-name/label and inbound `FlowDefinition` Id), and end with the one-line Outcome. Include the Omni Flow rows only when that path was taken. One line per item — no extra narrative, and do not omit a field that applies. If a step failed, still fill the fields reached and state the exact error and the step it failed at in Outcome.
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|-----------|-----------|
+| Never run an interactive login; require a pre-authenticated org alias | Auth and org lifecycle are out of scope; keeps the skill portable across surfaces |
+| Call APIs via `sf api request rest`; never extract the access token | Uses the CLI's stored session for `--target-org` — no raw token handling |
+| Never hardcode a queue Id / `SessionHandlerId` / `FlowDefinition` Id | These are org-specific; always resolve them (queue in Step 8, flow via `resolve-flow-definition.sh`) |
+| Attach routing via `SessionHandlerId` (+ `FallbackQueueId` for Omni Flow) — not `TargetQueueId` or `RoutingType` | Omni Queue: `SessionHandlerId` = queue Id. Omni Flow: `SessionHandlerId` = inbound `FlowDefinition` Id (`300…`), `FallbackQueueId` = queue Id |
+| Omni Flow: publish **and** activate the agent and deploy the inbound flow (Active, `300`-prefix) before creating the channel | The channel's `SessionHandlerId` points at a live inbound `FlowDefinition` that references a published, active agent |
+| Do not switch the agent's `plannerType` to `Atlas__VoiceAgent` | This org rejects it with an opaque error; keep the publish-generated `Atlas__ConcurrentMultiAgentOrchestration` — voice still routes via the `Copilot` flow (deviation) |
+| If the Agentforce prerequisite is unmet or agent/flow creation fails, stop and report unless the user explicitly accepts the Omni Queue fallback | Some runs require a new Agentforce agent and Omni Flow channel; do not silently downgrade the routing model |
+| Use `ChannelLineId` (not scalar `ChannelLine`) to link the CommunicationChannelLine | `ChannelLine` is the relationship name; the writable create field is `ChannelLineId` |
+| `MessageType` must be `PstnVoice` and `IsActive: true` | Required for an active inbound voice channel |
+| Do not set `IsoCountryCode` on `PstnVoice` channels | Not valid for this channel type |
+| Stop and report on any non-2xx API response | Partial setup left silent is worse than a clear failure |
+
+---
+
+## Gotchas
+
+| Issue | Resolution |
+|-------|------------|
+| `ChannelLine` not found immediately after procurement | Records propagate asynchronously — retry with backoff (Step 5 script handles this) |
+| Number `CodeStatus` not `Live` | Call `numberStateReconcile` and poll (Step 6 script); warn if it stays provisioning |
+| `INVALID_FIELD: The value provided for foreign key reference ChannelLine is not a nested SObject` on channel create | The relationship name `ChannelLine` was sent as a scalar field — send the Id in `ChannelLineId` |
+| `FIELD_INTEGRITY_EXCEPTION` blocking a non-live number | Expected when validation is enforced — wait for the number to become live, then retry |
+| Duplicate `DeveloperName` | A channel with that name exists — derive a unique name or reuse the existing channel |
+| Spaces in `phoneNumberType` (`Toll Free`) | URL-encode when building query strings (scripts handle this) |
+| `sf agent generate agent-spec` fails with `RequiresProjectError` | Run `scripts/prepare-agent-workdir.sh acc-voice-build`, then invoke `sf agent generate agent-spec` from inside `acc-voice-build` with `--output-file specs/<apiName>.yaml` |
+| `sf agent publish` says `default agent user NEW AGENT USER` | The generator left a placeholder in the `.agent` file — `create-voice-agent.sh` patches `default_agent_user` from the spec's `agentUser` before deploy/publish |
+| `sf agent publish` says `Unable to access the Salesforce Agent APIs` or `User doesn't have access to use agent` | Usually the spec/bundle used a generic Agent/Bot-profile user. Run `scripts/check-agentforce-prereq.sh`; it must return a user whose profile is exactly `Einstein Agent User` |
+| Opaque server error (e.g. `-1103525358`) when publishing/validating the agent | Caused by setting `plannerType: Atlas__VoiceAgent` — remove it and keep `Atlas__ConcurrentMultiAgentOrchestration` (deviation; `create-voice-agent.sh` never touches the planner) |
+| Routing flow deploy fails with `does not contain a valid Salesforce DX project` | Use the same prepared `acc-voice-build` work dir; `create-routing-flows.sh` now runs `sf project deploy start` from inside that directory |
+| `sf agent generate agent-spec` / publish fails on licensing or "default agent user" | Agentforce toggle is off or no Agentforce Service Agent User license is available. Enable it or free/provision a license (`references/agentforce-prerequisite.md`) |
+| Using a `Flow` Id (`301…`) as `SessionHandlerId` | Wrong handle — `SessionHandlerId` needs the stable `FlowDefinition` Id (`300…`); `resolve-flow-definition.sh` returns it |
+| Inbound flow deployed but the channel won't route to the agent | The agent must be **activated**, not just published, and the inbound flow must have an active version — `create-voice-agent.sh` verifies `BotVersion` is `Active`; `resolve-flow-definition.sh` exits 3 if there is no active version |
+
+---
+
+## Output Expectations
+
+This skill primarily creates records in the target org:
+
+- A procured phone number (Number Management).
+- An active `PstnVoice` `MessagingChannel` — routed to the contact center queue (Omni Queue) or to an Agentforce agent via an inbound routing flow with the queue as fallback (Omni Flow).
+- **Omni Flow only**: a published, active Agentforce agent plus two `RoutingFlow` flows (inbound `Copilot` + escalation `QueueBased`).
+- A report written per `assets/report-template.md`, plus a final summary table (`references/setup_summary.md`).
+
+The Omni Flow path also scaffolds a throwaway SFDX project under `acc-voice-build/` (spec, authoring bundle, flow metadata) to run the deploy — local build artifacts, not skill output.
+
+---
+
+## Cross-Skill Integration
+
+The Omni Flow path wires inbound voice itself (agent → inbound `Copilot` flow → channel, plus an escalation flow), so it does **not** hand that wiring off to a separate channel-configuration skill. Deeper agent authoring beyond the voice service agent this skill generates (custom topics, actions, knowledge) is out of scope.
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|-------------|
+| `references/number_management_api.md` | Steps 3–4 — Number Management endpoints, params, and status-code mapping |
+| `references/verification_and_errors.md` | Step 6 — live-verification polling strategy and error handling |
+| `references/messaging_channel.md` | Step 9 — MessagingChannel field contract (both routing models) and create-time error handling |
+| `references/omni-flow-routing.md` | Step 9 (Omni Flow) — routing-model contract, agent→flow→channel wiring order, new-vs-existing fork, planner deviation, fallback rule |
+| `references/agentforce-prerequisite.md` | Step 9 (Omni Flow) — Agentforce toggle prerequisite, preflight check, and Omni-Queue fallback |
+| `references/setup_summary.md` | Step 10 — user-facing summary table and next steps |
+| `assets/report-template.md` | Step 10 — exact structure for the written `report.md` |
+| `assets/omni-flow.flow-meta.xml` | Step 9 (Omni Flow) — inbound `Copilot` RoutingFlow template (rendered by `create-routing-flows.sh`) |
+| `assets/escalation-flow.flow-meta.xml` | Step 9 (Omni Flow) — escalation `QueueBased` RoutingFlow template (rendered by `create-routing-flows.sh`) |
+| `scripts/prepare-agent-workdir.sh` | Step 9 (Omni Flow) — prepare the SFDX project context required before generating an agent spec |
+| `scripts/fetch-numbers.sh` | Step 3 — fetch available default numbers |
+| `scripts/procure-number.sh` | Step 4 — procure the selected number |
+| `scripts/resolve-channel-line.sh` | Step 5 — resolve the CommunicationChannelLine with retry |
+| `scripts/verify-number-live.sh` | Step 6 — verify/reconcile live status |
+| `scripts/resolve-acc-queue.sh` | Step 8 — resolve the ACC default queue Id |
+| `scripts/create-voice-channel.sh` | Step 9 — create the active PstnVoice channel (4-arg Omni Queue / 5-arg Omni Flow) |
+| `scripts/check-agentforce-prereq.sh` | Step 9 (Omni Flow) — prerequisite gate; resolves the Einstein Agent User for `--agent-user` |
+| `scripts/create-voice-agent.sh` | Step 9 (Omni Flow) — generate/validate/publish/activate the Agentforce voice agent |
+| `scripts/create-routing-flows.sh` | Step 9 (Omni Flow) — deploy inbound + escalation flows; print the inbound `FlowDefinition` Id |
+| `scripts/resolve-flow-definition.sh` | Step 9 (Omni Flow) — resolve an inbound flow's `FlowDefinition` Id (`300…`), incl. reusing an existing flow |

package/skills/service-agentforce-contact-center-coordinate/assets/escalation-flow.flow-meta.xml

@@ -0,0 +1,72 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Escalation voice flow (RoutingFlow, routingType=QueueBased). Routes a call from the agent
+     to the fallback queue when the caller asks for a human. Rendered by
+     scripts/create-routing-flows.sh (which fills the FLOW_LABEL, QUEUE_ID, and QUEUE_LABEL tokens). -->
+<Flow xmlns="http://soap.sforce.com/2006/04/metadata">
+    <actionCalls>
+        <name>Route_to_Voice_Queue</name>
+        <label>Route to Voice Queue</label>
+        <locationX>176</locationX>
+        <locationY>158</locationY>
+        <actionName>routeWork</actionName>
+        <actionType>routeWork</actionType>
+        <flowTransactionModel>CurrentTransaction</flowTransactionModel>
+        <inputParameters>
+            <name>recordId</name>
+            <value><elementReference>recordId</elementReference></value>
+        </inputParameters>
+        <inputParameters>
+            <name>serviceChannelLabel</name>
+            <value><stringValue>Phone</stringValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>serviceChannelDevName</name>
+            <value><stringValue>sfdc_phone</stringValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>serviceChannelId</name>
+            <value>
+                <setupReference>sfdc_phone</setupReference>
+                <setupReferenceType>ServiceChannel</setupReferenceType>
+            </value>
+        </inputParameters>
+        <inputParameters>
+            <name>routingType</name>
+            <value><stringValue>QueueBased</stringValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>queueLabel</name>
+            <value><stringValue>{{QUEUE_LABEL}}</stringValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>queueId</name>
+            <value><stringValue>{{QUEUE_ID}}</stringValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>isQueueVariable</name>
+            <value><booleanValue>false</booleanValue></value>
+        </inputParameters>
+    </actionCalls>
+    <apiVersion>68.0</apiVersion>
+    <environments>Default</environments>
+    <interviewLabel>{{FLOW_LABEL}} {!$Flow.CurrentDateTime}</interviewLabel>
+    <label>{{FLOW_LABEL}}</label>
+    <processMetadataValues>
+        <name>BuilderType</name>
+        <value><stringValue>LightningFlowBuilder</stringValue></value>
+    </processMetadataValues>
+    <processType>RoutingFlow</processType>
+    <start>
+        <locationX>50</locationX>
+        <locationY>0</locationY>
+        <connector><targetReference>Route_to_Voice_Queue</targetReference></connector>
+    </start>
+    <status>Active</status>
+    <variables>
+        <name>recordId</name>
+        <dataType>String</dataType>
+        <isCollection>false</isCollection>
+        <isInput>true</isInput>
+        <isOutput>false</isOutput>
+    </variables>
+</Flow>

package/skills/service-agentforce-contact-center-coordinate/assets/omni-flow.flow-meta.xml

@@ -0,0 +1,85 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Inbound voice Omni Flow (RoutingFlow, routingType=Copilot). Routes arriving calls to the
+     Agentforce agent, with the queue as fallback when the agent is unavailable. Rendered by
+     scripts/create-routing-flows.sh (which fills the FLOW_LABEL, AGENT_API_NAME, AGENT_LABEL,
+     QUEUE_ID, and QUEUE_LABEL tokens); the channel's SessionHandlerId points at this flow's
+     FlowDefinition Id. -->
+<Flow xmlns="http://soap.sforce.com/2006/04/metadata">
+    <actionCalls>
+        <name>Route_to_Agent</name>
+        <label>Route to Agent</label>
+        <locationX>176</locationX>
+        <locationY>158</locationY>
+        <actionName>routeWork</actionName>
+        <actionType>routeWork</actionType>
+        <flowTransactionModel>CurrentTransaction</flowTransactionModel>
+        <inputParameters>
+            <name>recordId</name>
+            <value><elementReference>recordId</elementReference></value>
+        </inputParameters>
+        <inputParameters>
+            <name>serviceChannelLabel</name>
+            <value><stringValue>Phone</stringValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>serviceChannelDevName</name>
+            <value><stringValue>sfdc_phone</stringValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>serviceChannelId</name>
+            <value>
+                <setupReference>sfdc_phone</setupReference>
+                <setupReferenceType>ServiceChannel</setupReferenceType>
+            </value>
+        </inputParameters>
+        <inputParameters>
+            <name>routingType</name>
+            <value><stringValue>Copilot</stringValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>copilotLabel</name>
+            <value><stringValue>{{AGENT_LABEL}}</stringValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>copilotId</name>
+            <value>
+                <setupReference>{{AGENT_API_NAME}}</setupReference>
+                <setupReferenceType>BotDefinition</setupReferenceType>
+            </value>
+        </inputParameters>
+        <inputParameters>
+            <name>queueLabel</name>
+            <value><stringValue>{{QUEUE_LABEL}}</stringValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>queueId</name>
+            <value><stringValue>{{QUEUE_ID}}</stringValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>isQueueVariable</name>
+            <value><booleanValue>false</booleanValue></value>
+        </inputParameters>
+    </actionCalls>
+    <apiVersion>68.0</apiVersion>
+    <environments>Default</environments>
+    <interviewLabel>{{FLOW_LABEL}} {!$Flow.CurrentDateTime}</interviewLabel>
+    <label>{{FLOW_LABEL}}</label>
+    <processMetadataValues>
+        <name>BuilderType</name>
+        <value><stringValue>LightningFlowBuilder</stringValue></value>
+    </processMetadataValues>
+    <processType>RoutingFlow</processType>
+    <start>
+        <locationX>50</locationX>
+        <locationY>0</locationY>
+        <connector><targetReference>Route_to_Agent</targetReference></connector>
+    </start>
+    <status>Active</status>
+    <variables>
+        <name>recordId</name>
+        <dataType>String</dataType>
+        <isCollection>false</isCollection>
+        <isInput>true</isInput>
+        <isOutput>false</isOutput>
+    </variables>
+</Flow>

package/skills/service-agentforce-contact-center-coordinate/assets/report-template.md

@@ -0,0 +1,52 @@
+# Agentforce Contact Center Setup Report
+
+## Setup
+
+| Item | Value |
+|------|-------|
+| Org alias | `<alias>` |
+| Org confirmed | `sf org display --target-org <alias>` → `<instanceUrl>` |
+| Country | `<US\|CA>` |
+| Phone number type | `<10DLC\|Toll Free>` |
+| Routing model | `<Omni Queue \| Omni Flow>` |
+
+## Commands run
+
+Each API call went through `sf api request rest` (no raw access token was extracted).
+
+1. Fetch numbers — `GET /services/data/v68.0/connect/number-management/v1/numbers?countryCode=<country>&phoneNumberType=<type>`
+2. Procure number — `POST /services/data/v68.0/connect/number-management/v1/number` with `country=<country>`, `phoneNumberType=<type>`
+3. Resolve ChannelLine — SOQL: `<query used>`
+4. Verify live status — Tooling API `CodeStatus`<, numberStateReconcile if not live>
+5. Resolve queue by name — SOQL: `SELECT Id FROM Group WHERE Type='Queue' AND Name='<queue-name>'`
+6. Create channel — `POST` MessagingChannel (`PstnVoice`, `ChannelLineId=<channel-line-id>`, `IsActive=true`)
+
+**Omni Flow only** — additional steps (omit for Omni Queue):
+
+7. Agentforce prerequisite — `scripts/check-agentforce-prereq.sh` → canonical Einstein Agent User `<agent-user>` <reused/provisioned>
+8. Agent — created/reused `<agent-api-name>` (`<agent-label>`), status Active
+9. RoutingFlows — deployed `<agent-api-name>_Voice_Omni_Flow` (Copilot) + `<agent-api-name>_Voice_Escalation` (QueueBased)
+
+## Result
+
+| Field | Value |
+|-------|-------|
+| Routing model | `<Omni Queue \| Omni Flow>` |
+| Procured phone number | `<number>` |
+| CommunicationChannelLine Id | `<channel-line-id>` |
+| CommunicationChannelLine status | `<code-status>` |
+| Queue resolved by name | `<queue-name>` → `<queue-id>` |
+| Agentforce agent (Omni Flow) | `<agent-api-name>` (`<agent-label>`) — Active |
+| Inbound FlowDefinition (Omni Flow) | `<flow-dev-name>` → `<300-id>` |
+| MessagingChannel Id | `<channel-id>` |
+| MessagingChannel DeveloperName | `<dev-name>` |
+| MessagingChannel ChannelLineId | `<channel-line-id>` |
+| MessagingChannel IsActive | `true` |
+| MessagingChannel SessionHandlerId | `<queue-id \| 300-flowdefinition-id>` |
+| MessagingChannel FallbackQueueId | `<queue-id (Omni Flow) \| null>` |
+
+Fill the Omni Flow rows only when that path was taken; leave them out for Omni Queue.
+
+## Outcome
+
+<One line: SUCCESS — active PstnVoice channel `<channel-id>` routed to `<queue `<queue-name>` (Omni Queue) | agent `<agent-label>` via Omni Flow, fallback queue `<queue-name>`>`; OR the exact error encountered and the step it failed at.>

package/skills/service-agentforce-contact-center-coordinate/references/agentforce-prerequisite.md

@@ -0,0 +1,31 @@
+# Prerequisite — Einstein Setup + Agentforce Agents toggle
+
+The **Omni Flow** path (routing a voice channel to an Agentforce agent) requires **Einstein** and **Agentforce / Einstein Service Agents to be enabled** in the org. When they're on, the org can provide an **Einstein Agent User** — the `--agent-user` that `sf agent generate agent-spec` and publish require. When they're off, or when no Agentforce Service Agent User license is available, agent authoring/publish fails with a licensing, Agent API access, or "couldn't find the default agent user" error.
+
+This prerequisite does **not** apply to the Omni Queue path.
+
+## Enable it (org admin, one time)
+
+In the target org, in the Setup UI:
+
+1. **Setup → Einstein Setup** → turn **Einstein** **On** (this must be enabled before the Agentforce toggle appears/works).
+2. **Setup → Einstein → Agentforce (Agents)** (a.k.a. *Einstein Agent* / *Agentforce Service Agents*) → turn the setting **On**.
+3. Confirm an **Einstein Agent User** exists (Setup → Users), or let `scripts/check-agentforce-prereq.sh` provision one with `sf org create agent-user`.
+
+Enablement is an org preference, not part of this skill's scope — the operator flips it in Setup.
+
+## Preflight check
+
+```bash
+scripts/check-agentforce-prereq.sh <alias>
+```
+
+- **Exit 0** — prints a user whose profile is exactly `Einstein Agent User`. Use it as `--agent-user` for `sf agent generate agent-spec`. The script reuses an existing user, or provisions one with `sf org create agent-user`.
+- **Exit 3** — no canonical Einstein Agent User could be found or provisioned; the toggle is likely off or the org has no available Agentforce Service Agent User license.
+
+The profile-name check is intentionally strict. Do not use a broad fallback such as `Profile.Name LIKE '%Agent%'` or `Profile.Name LIKE '%Bot%'`: those users can make spec generation/validation appear healthy, then fail `sf agent publish authoring-bundle` with Agent API access or default-agent-user errors.
+
+## When the toggle is off
+
+1. **Prompt the user** to enable it or free/provision an Agentforce Service Agent User license, then re-run the check.
+2. If it still can't be confirmed — or agent/flow creation later fails on licensing — stop and report unless the user explicitly accepts the Omni Queue fallback.

package/skills/service-agentforce-contact-center-coordinate/references/messaging_channel.md

@@ -0,0 +1,76 @@
+# PstnVoice MessagingChannel
+
+**`POST /services/data/v68.0/sobjects/MessagingChannel/`**
+
+All calls go through `sf api request rest` — never extract the access token.
+
+`SessionHandlerId` is the routing target: the **ACC queue Id** for Omni Queue, or the inbound
+**FlowDefinition Id** (`300…`) for Omni Flow (with `FallbackQueueId` set to the queue). Both are
+produced by `scripts/create-voice-channel.sh` — its optional 5th `fallback-queue-id` arg switches
+it to Omni Flow. See `references/omni-flow-routing.md` for the Omni Flow contract.
+
+## Request — Omni Queue (default)
+
+```bash
+sf api request rest \
+  "/services/data/v68.0/sobjects/MessagingChannel/" \
+  --method POST \
+  --body '{
+    "DeveloperName": "Voice_Channel_14155551234",
+    "MasterLabel": "Voice Channel +14155551234",
+    "MessageType": "PstnVoice",
+    "MessagingPlatformKey": "+14155551234",
+    "ChannelLineId": "<communication-channel-line-id>",
+    "IsActive": true,
+    "SessionHandlerId": "<acc-queue-id>"
+  }' \
+  --target-org <alias>
+```
+
+## Request — Omni Flow
+
+Same call, but `SessionHandlerId` is the inbound FlowDefinition Id and `FallbackQueueId` is added:
+
+```json
+{
+  "...": "same fields as above",
+  "SessionHandlerId": "<inbound-flowdefinition-id-300>",
+  "FallbackQueueId": "<acc-queue-id>"
+}
+```
+
+## Field rules
+
+| Field | Rule |
+|-------|------|
+| `MessageType` | Must be `PstnVoice` |
+| `MessagingPlatformKey` | The E.164 phone number (with leading `+`) |
+| `SessionHandlerId` | Omni Queue: the ACC queue Id (`00G…`). Omni Flow: the inbound RoutingFlow's `FlowDefinition` Id (`300…`). Resolve both — never hardcode |
+| `FallbackQueueId` | Omni Flow only: the queue the agent overflows/escalates to (`00G…`). Omit for Omni Queue |
+| `ChannelLineId` | The Id from `CommunicationChannelLine`; this is the writable create field that populates the `ChannelLine` relationship |
+| `IsActive` | `true` activates the channel immediately |
+| `IsoCountryCode` | Do NOT set on `PstnVoice` channels |
+| Routing | Use `SessionHandlerId` (+ `FallbackQueueId` for Omni Flow) — not `TargetQueueId` or `RoutingType` |
+
+## Success response
+
+```json
+{ "id": "0Mj...", "success": true, "errors": [] }
+```
+
+## Create-time errors
+
+| Error | Meaning | Action |
+|-------|---------|--------|
+| `INVALID_FIELD: The value provided for foreign key reference ChannelLine is not a nested SObject` | The relationship name `ChannelLine` was used as a scalar Id field | Send the `CommunicationChannelLine` Id in `ChannelLineId` instead |
+| `FIELD_INTEGRITY_EXCEPTION: ... status 'Provisioning'` | Number not yet live and validation is enforced | Wait for the number to become live (Step 6), then retry |
+| Duplicate `DeveloperName` | A channel with that name exists | Derive a unique `DeveloperName` or reuse the existing channel |
+
+## Verify
+
+```sql
+SELECT Id, DeveloperName, MasterLabel, MessageType, MessagingPlatformKey, ChannelLineId, IsActive, SessionHandlerId, FallbackQueueId
+FROM MessagingChannel WHERE Id = '<channel-id>'
+```
+
+For Omni Flow, `SessionHandlerId` must start with `300` (inbound FlowDefinition) and `FallbackQueueId` with `00G` (queue). For Omni Queue, `SessionHandlerId` starts with `00G` and `FallbackQueueId` is null.

package/skills/service-agentforce-contact-center-coordinate/references/number_management_api.md

@@ -0,0 +1,78 @@
+# Number Management API
+
+All endpoints share the base path `/services/data/v68.0/connect/number-management/v1`.
+
+**Never extract the access token.** All calls go through `sf api request rest`, which uses
+the CLI's stored session for `--target-org`. Do not pull `accessToken` out of `sf org display`
+and hand-build an HTTP request with it.
+
+**Never pass `--json` to `sf api request rest`.** This beta command has no `--json` flag —
+passing it fails with `Error: Nonexistent flag: --json`. The raw stdout body is already JSON
+(unlike `sf data query`, which does support and need `--json` for its `.result.records[]`
+envelope).
+
+## Fetch available default numbers
+
+**`GET /numbers`**
+
+Query parameters:
+
+| Param | Values | Notes |
+|-------|--------|-------|
+| `countryCode` | `US`, `CA` | |
+| `phoneNumberType` | `10DLC`, `Toll Free` | URL-encode the space in `Toll Free` as `%20` |
+
+```bash
+sf api request rest \
+  "/services/data/v68.0/connect/number-management/v1/numbers?countryCode=US&phoneNumberType=Toll%20Free" \
+  --target-org <alias>
+```
+
+Response:
+
+```json
+{ "phoneNumbers": ["+14155551234", "+14155551235", "+14155551236"] }
+```
+
+## Procure a number
+
+**`POST /number`**
+
+```bash
+sf api request rest \
+  "/services/data/v68.0/connect/number-management/v1/number" \
+  --method POST \
+  --body '{"phoneNumberType":"Toll Free","country":"US","phoneNumber":"+14155551234"}' \
+  --target-org <alias>
+```
+
+Success (`201`):
+
+```json
+{ "phoneNumber": "+14155551234" }
+```
+
+## Reconcile number state
+
+**`POST /numberStateReconcile`**
+
+```bash
+sf api request rest \
+  "/services/data/v68.0/connect/number-management/v1/numberStateReconcile" \
+  --method POST \
+  --body '{"phoneNumber":"+14155551234"}' \
+  --target-org <alias>
+```
+
+Success (`200`): empty body. Used to force the platform to reconcile a procured
+number's downstream `CommunicationChannelLine` state.
+
+## Status-code mapping
+
+| Status | Meaning | Action |
+|--------|---------|--------|
+| `400 BAD_REQUEST` | Invalid country / number type / field | Fix the input and retry |
+| `403 RESOURCE_NOT_AVAILABLE` | Max number limit reached | Stop; user must free capacity or request more |
+| `404 NOT_FOUND` | Number does not exist (procurement likely failed) | Re-run procurement |
+| `409 CONFLICT` | Number already procured | Ask the user to select a different number |
+| `500 INTERNAL_SERVER_ERROR` | Backend failure | Retry after a few seconds; escalate if persistent |