@salesforce/afv-skills 1.65.0 → 1.66.0

package/skills/platform-widget-generate/SKILL.md

@@ -2,17 +2,16 @@
 name: platform-widget-generate
 description: "Use this skill to author a complete HXL WidgetBundle (UEM body + schema.json + -meta.xml). TRIGGER when: user asks for a widget, mosaic, fragment, card, or rich UI surface for any subject, domain, feature, or entity noun; the prompt names only an entity or data shape without invoking Lightning Types, CLTs, or Apex-backed types. DO NOT TRIGGER when: the prompt explicitly says 'Lightning Type', 'CLT', 'Custom Lightning Type', 'Apex-backed type', or references '@apexClassType/...' (use platform-lightning-type-widget-coordinate); authoring a custom-LWC renderer for a Custom Lightning Type (use platform-custom-lightning-type-generate); or editing only an LWC component."
 metadata:
-  version: "1.4"
+  version: "1.5"
   domains: ["Platform", "Agentforce"]
   minApiVersion: "68.0"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
   relatedSkills:
     - "platform-apex-generate"
     - "platform-custom-lightning-type-generate"
     - "platform-lightning-type-widget-coordinate"
-  mcpTools:
-    metadata-experts:
-      tools: ["execute_metadata_action"]
-      semver: ">=1.0.0"
 ---
 
 # Generating a Widget Bundle
@@ -67,23 +66,49 @@ The first child of `tile/widget.children` SHOULD be a single `tile/column`. All
 
 ---
 
-## Available Metadata Actions
+## Available Invocable Actions
+
+Both are standard invocable actions on the target org.
+
+### Calling Convention
+
+Fire each action with whichever mechanism is available: the H360 MCP `dispatch` tool (a `POST` to the endpoint path with the request body) or `sf api request rest`. Use `v{version}` = this skill's `minApiVersion`. Never use `curl`, and never extract the org's access token.
+
+```bash
+sf api request rest '/services/data/v{version}/actions/standard/<actionName>' --method POST --body '<request body>' --target-org <org>
+```
+
+### Response Handling
+
+Each response is an array with one envelope (`dispatch` nests it under `body`). Check three failure layers, in order:
+
+| Layer | Signal | Action |
+|---|---|---|
+| Transport / auth | `dispatch` `status_code` is not 200, or CLI exits non-zero | Surface the error |
+| Action | `[0].isSuccess` is `false`, or `[0].errors` is non-empty | Surface `errors[].message` |
+| Per-entry (`getUiComponentSchemas` only) | any `componentSchemas[].success` is `false`, even when `[0].isSuccess` is `true` | Treat that block as unavailable |
+
+On success, read `[0].outputValues`.
 
 ### discoverUiComponents
 
 **Purpose:** Discover the palette of blocks available for composition.
 
-**Required parameters:** `actionName: "discoverUiComponents"`, `metadataType: "FRAGMENT"`, `parameters.pageType: "FRAGMENT"`. Optional: `searchQuery` to filter by name/description.
+**Endpoint:** `POST /services/data/v{version}/actions/standard/discoverUiComponents`
+
+**Request body:** `{"inputs":[{"pageType":"FRAGMENT"}]}`
 
-**Returns:** list of `{ definition, description, label, attributes? }`.
+**Returns:** `outputValues.componentDefinitions[]` — list of `{ definition, description, label }`.
 
 ### getUiComponentSchemas
 
-**Purpose:** Fetch JSON schemas (property types, required vs optional, validation) for selected blocks.
+**Purpose:** Fetch schemas (property types, required vs optional, validation) for selected blocks.
 
-**Required parameters:** `actionName: "getUiComponentSchemas"`, `metadataType: "FRAGMENT"`, `parameters.pageType: "FRAGMENT"`, `parameters.componentDefinitions: ["namespace/definition", ...]`. Optional: `includeKnowledge` (default `true`).
+**Endpoint:** `POST /services/data/v{version}/actions/standard/getUiComponentSchemas`
 
-**Returns:** `componentSchemas[]` — success entries carry the JSON schema, failure entries carry an error message. Partial failures are supported.
+**Request body:** `{"inputs":[{"pageType":"FRAGMENT","componentDefinitions":["namespace/definition", ...]}]}`
+
+**Returns:** `outputValues.componentSchemas[]` — list of `{ definition, success, schema }` (`schema` is a YAML string). Partial failures are supported.
 
 > Never pass `tile/widget` to `getUiComponentSchemas` — it is a fixed wrapper, not a queryable component.
 
@@ -169,11 +194,11 @@ Widgets express *intent*, not pixels. Each surface provides a default look and f
    - If `lightningTypeSchema` was passed by the orchestrator → derive per `references/schema-from-lightning-type.md`.
    - Otherwise → infer the list directly from the user prompt (pasted JSON payload, enumerated field list, or descriptive prose).
 
-2. **Discover blocks (REQUIRED — do NOT skip).** Call the `discoverUiComponents` metadata action via `execute_metadata_action`. Use property types from the widget spec to seed `searchQuery` (text → `"text"`, number → `"number"`). **If `discoverUiComponents` returns `success: false`, an error, or an empty list, STOP and surface the error verbatim — do not improvise block names from memory, prior runs, or training data. Re-run discover with a different `searchQuery` only if the failure is search-query-specific.**
+2. **Discover blocks (REQUIRED — do NOT skip).** Call the `discoverUiComponents` invocable action (see *Available Invocable Actions*) and match widget-spec property types against the returned `label`/`description` values. **If `isSuccess` is `false`, `errors` is non-empty, or `componentDefinitions` is empty, STOP and surface the error verbatim — do not improvise block names from memory, prior runs, or training data.**
 
 3. **Select blocks.** Choose one block per widget-spec property, plus structural primitives from *Layout Best Practices*.
 
-4. **Get block schemas (REQUIRED — do NOT skip).** Call the `getUiComponentSchemas` metadata action via `execute_metadata_action` for the selected blocks. Review property metadata. **If `componentSchemas` returns all-failure or empty, STOP and surface the error — do not improvise from existing widgets in the project.**
+4. **Get block schemas (REQUIRED — do NOT skip).** Call the `getUiComponentSchemas` invocable action for the selected blocks. Review property metadata. **If `isSuccess` is `false`, `componentSchemas` is empty, or any entry has `success: false`, do not use that block — re-select a different one from step 2's results; if none works, STOP and surface the error. Never improvise from existing widgets in the project.**
 
 5. **Build the UEM tree (example reads REQUIRED — do NOT skip).** First, identify which patterns match the widget spec and read each matching example file from this skill's own `examples/` directory (`<skill-root>/examples/`):
 
@@ -236,17 +261,8 @@ Widgets express *intent*, not pixels. Each surface provides a default look and f
 
    Write all three before proceeding to self-validation.
 
-9. **Self-validate.** Before reporting, confirm each check below and report each result individually (`pass` or `fail (<reason>)`). Do **not** summarize as a single "all passed" line — list every check so a reviewer can spot a silent skip.
-    - **`schema-parses`** — `<pkgDir>/uiWidgets/<widgetName>/schema.json` parses as JSON.
-    - **`schema-root-keys`** — root has `title` (string), `type: "object"`, and `properties.attributes` (object) — where `properties.attributes` carries `lightning:type: "lightning__objectType"` and a nested `properties` map. No `unevaluatedProperties: false`.
-    - **`schema-leaf-types`** — every leaf under `properties.attributes.properties` carries a `lightning:type`. Singular nested inner-class fields carry `lightning:type` set to the inner Apex class reference (`@apexClassType/<namespace>__<OuterClass>$<InnerClass>`); the nested shape is not redeclared. `List<InnerClass>` fields carry `lightning:type: "lightning__listType"` with `items.lightning:type` set to the inner Apex class reference (`@apexClassType/<namespace>__<OuterClass>$<InnerClass>`), not a redeclared field map — see `references/schema-from-lightning-type.md`. **When the list has no Apex-backed type** (schema inferred from the prompt), `items.lightning:type: "lightning__objectType"` MUST carry an inline nested `properties` map for every item field the body binds via `{!$item.X}`.
-    - **`bindings-resolve`** — every `{!$attrs.X}` (or `{!$attrs.<outerField>.<innerField>}` for nested objects) in `<widgetName>.json` resolves to a property under `schema.json` `properties.attributes.properties`, and every `{!$item.X}` resolves to a `forItem` loop variable defined upstream. This applies to `$attrs`/`$item` references **inside formula expressions** too.
-    - **`formulas-supported`** — every function name used inside a `{!...}` expression appears in the *Supported functions* list in `references/widget-formulas.md`.
-    - **`body-envelope`** — `<widgetName>.json` root has `type: "lightning__agentforceWidget"` and a `contentBody` object whose `widgetBody` carries the UEM tree rooted at `tile/widget`. No node in the tree — root or non-root — carries a `type` key.
-    - **`metaxml-wellformed`** — `<widgetName>.uiwidget-meta.xml` parses as well-formed XML.
-    - **`metaxml-elements`** — `<widgetName>.uiwidget-meta.xml` has root `<UiWidgetBundle>` and contains `<masterLabel>` (non-empty), `<description>` (non-empty), and `<widgetType>JSON</widgetType>`.
-    - **`files-present`** — all three files exist at the resolved `<pkgDir>/uiWidgets/<widgetName>/` path.
-    - **`button-actions-present`** — every `tile/button` in `<widgetName>.json` has an `actions.click` action node whose `definition` is `action/openLink` or `action/sendMessage`.
+9. **Self-validate.** Before reporting, run the checks and report each result individually (`pass` or `fail (<reason>)`). Do **not** summarize as a single "all passed" line — list every check so a reviewer can spot a silent skip.
+Run every check in `references/widget-bundle-validation.md`.
 
 ---
 
@@ -256,7 +272,7 @@ Widgets express *intent*, not pixels. Each surface provides a default look and f
 |---|---|
 | Block definitions follow `{namespace}/{blockName}` and must match `discoverUiComponents` output | Runtime resolves blocks by exact definition string |
 | Never pass `tile/widget` to `getUiComponentSchemas` | It is a fixed wrapper, not a queryable component |
-| Always supply `parameters` (with required keys) when calling `execute_metadata_action` | Missing parameters cause hard failure, not partial result |
+| Read `references/` and `examples/` files only at the step that names them | Upfront reads waste context and precede the discovery result that determines which files are needed |
 | Every `{!$attrs.X}` in the body resolves to a property in the widget `schema.json` | No invented fields |
 | Every `tile/button` carries an `actions.click` entry using `action/openLink` or `action/sendMessage` only | These are the only two supported tile action definitions; an action-less button renders disabled |
 | No `$(…)`, backticks, `<(…)`, brace expansion `{a,b,c}`, or `eval`/`exec` in any Bash tool call | Vibes' safe-shell filter forces manual approval on these patterns even in Bypass mode. Emit separate commands (`mkdir -p a && mkdir -p b`) or print each value with its own command and reason about the output — do not capture into a shell variable |
@@ -265,26 +281,27 @@ Widgets express *intent*, not pixels. Each surface provides a default look and f
 
 ## Gotchas
 
-| Issue | Resolution                                                                                                                                                                                                                                                     |
-|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `getUiComponentSchemas` returns a partial-failure entry | Pick a different block from `discoverUiComponents`; do not silently continue without a schema                                                                                                                                                                  |
-| Body references `{!$attrs.foo}` but `foo` is not under `schema.json` `properties.attributes.properties` | Add `foo` to `schema.json` `properties.attributes.properties` OR remove the body reference                                                                                                                                                                     |
+| Issue | Resolution|
+|---|---|
+| `getUiComponentSchemas` returns a partial-failure entry | Pick a different block from `discoverUiComponents`; do not silently continue without a schema|
+| Body references `{!$attrs.foo}` but `foo` is not under `schema.json` `properties.attributes.properties` | Add `foo` to `schema.json` `properties.attributes.properties` OR remove the body reference|
 | Output written outside `<pkgDir>/uiWidgets/<widgetName>/` | `<pkgDir>` = `<packageDirectories[].path>/main/default` (see `references/widget-bundle-layout.md`). Dropping the `main/default/` segment is the common cause of widgets landing at `force-app/uiWidgets/...` instead of `force-app/main/default/uiWidgets/...` |
-| `if` bound directly to a raw string or number relies on truthiness and is unreliable | Bind to a `lightning__booleanType` property, or use a formula comparison that evaluates to boolean                                                                                                                                                             |
-| `tile/button` renders but does nothing when clicked | No `actions.click` entry was set — an action-less button renders disabled by design. Add one (see *Actions* above)                                                                                                                                             |
-| Using `action/sendMessage` for pure navigation, or `action/openLink` when the agent should respond | `action/openLink` is synchronous and does not consume a turn; `action/sendMessage` is asynchronous and earns a fresh turn. Pick the one matching the intended UX                                                                                               |
+| `if` bound directly to a raw string or number relies on truthiness and is unreliable | Bind to a `lightning__booleanType` property, or use a formula comparison that evaluates to boolean|
+| `tile/button` renders but does nothing when clicked | No `actions.click` entry was set — an action-less button renders disabled by design. Add one (see *Actions* above)|
+| Using `action/sendMessage` for pure navigation, or `action/openLink` when the agent should respond | `action/openLink` is synchronous and does not consume a turn; `action/sendMessage` is asynchronous and earns a fresh turn. Pick the one matching the intended UX|
 
 ---
 
 ## Reference File Index
 
-| File | When to read                                                                                                                                                                        |
-|---|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `references/widget-meta-directives.md` | For `forEach` / `forItem` (iteration) and `if` (conditional rendering), including nested loops                                                                                      |
-| `references/schema-from-lightning-type.md` | When `lightningTypeSchema` is provided; how to derive the widget `schema.json` from an Apex-backed Lightning Type                                                                   |
-| `references/widget-bundle-layout.md` | Folder layout, `-meta.xml` shape, `<pkgDir>` resolution rules                                                                                                                       |
-| `references/widget-formulas.md` | Supported formula functions and operators                                                                                                                                           |
-| `examples/single-object.json` | Single-object pattern (root binding via `{!$attrs.X}`, no iteration)                                                                                                                |
+| File | When to read|
+|---|---|
+| `references/widget-meta-directives.md` | For `forEach` / `forItem` (iteration) and `if` (conditional rendering), including nested loops|
+| `references/schema-from-lightning-type.md` | When `lightningTypeSchema` is provided; how to derive the widget `schema.json` from an Apex-backed Lightning Type|
+| `references/widget-bundle-layout.md` | Folder layout, `-meta.xml` shape, `<pkgDir>` resolution rules|
+| `references/widget-bundle-validation.md` | Step 9 — the checks to run before reporting |
+| `references/widget-formulas.md` | Supported formula functions and operators|
+| `examples/single-object.json` | Single-object pattern (root binding via `{!$attrs.X}`, no iteration)|
 | `examples/list-with-foreach.json` | Any list-iteration case — root-level collections, nested lists, and lists embedded inside a single-object widget (e.g. iterating a `List<InnerClass>` inside an outer Apex payload) |
-| `examples/conditional.json` | Conditional pattern (`if` on `meta`, including `if` + `forEach` together)                                                                                                           |
-| `examples/formulas.json` | Formula usage — text/arithmetic/date transforms, `IF`/`AND`/`NOT` driving both a `tile/text` and `meta.if`                                                                          |
+| `examples/conditional.json` | Conditional pattern (`if` on `meta`, including `if` + `forEach` together)|
+| `examples/formulas.json` | Formula usage — text/arithmetic/date transforms, `IF`/`AND`/`NOT` driving both a `tile/text` and `meta.if`|

package/skills/platform-widget-generate/references/widget-bundle-validation.md

@@ -0,0 +1,14 @@
+# Widget Bundle Validation Checks
+
+Report each check individually as `pass` or `fail (<reason>)`.
+
+- **`schema-parses`** — `<pkgDir>/uiWidgets/<widgetName>/schema.json` parses as JSON.
+- **`schema-root-keys`** — root has `title` (string), `type: "object"`, and `properties.attributes` (object) — where `properties.attributes` carries `lightning:type: "lightning__objectType"` and a nested `properties` map. No `unevaluatedProperties: false`.
+- **`schema-leaf-types`** — every leaf under `properties.attributes.properties` carries a `lightning:type`. Singular nested inner-class fields carry `lightning:type` set to the inner Apex class reference (`@apexClassType/<namespace>__<OuterClass>$<InnerClass>`); the nested shape is not redeclared. `List<InnerClass>` fields carry `lightning:type: "lightning__listType"` with `items.lightning:type` set to the inner Apex class reference (`@apexClassType/<namespace>__<OuterClass>$<InnerClass>`), not a redeclared field map — see `references/schema-from-lightning-type.md`. **When the list has no Apex-backed type** (schema inferred from the prompt), `items.lightning:type: "lightning__objectType"` MUST carry an inline nested `properties` map for every item field the body binds via `{!$item.X}`.
+- **`bindings-resolve`** — every `{!$attrs.X}` (or `{!$attrs.<outerField>.<innerField>}` for nested objects) in `<widgetName>.json` resolves to a property under `schema.json` `properties.attributes.properties`, and every `{!$item.X}` resolves to a `forItem` loop variable defined upstream. This applies to `$attrs`/`$item` references **inside formula expressions** too.
+- **`formulas-supported`** — every function name used inside a `{!...}` expression appears in the *Supported functions* list in `references/widget-formulas.md`.
+- **`body-envelope`** — `<widgetName>.json` root has `type: "lightning__agentforceWidget"` and a `contentBody` object whose `widgetBody` carries the UEM tree rooted at `tile/widget`. No node in the tree — root or non-root — carries a `type` key.
+- **`metaxml-wellformed`** — `<widgetName>.uiwidget-meta.xml` parses as well-formed XML.
+- **`metaxml-elements`** — `<widgetName>.uiwidget-meta.xml` has root `<UiWidgetBundle>` and contains `<masterLabel>` (non-empty), `<description>` (non-empty), and `<widgetType>JSON</widgetType>`.
+- **`files-present`** — all three files exist at the resolved `<pkgDir>/uiWidgets/<widgetName>/` path.
+- **`button-actions-present`** — every `tile/button` in `<widgetName>.json` has an `actions.click` action node whose `definition` is `action/openLink` or `action/sendMessage`.

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

@@ -55,7 +55,7 @@ All steps are sequential. If a step fails, stop and report the error rather than
 
 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.
+3. **Fetch available numbers** — read `references/number_management_api.md` for the endpoint contract. Before fetching, use `AskUserQuestion` to offer an **optional** way to narrow results: ask whether the user wants numbers for a specific **area code** (when the type is `10DLC`) or **prefix** (when the type is `Toll Free`), or to list all available numbers. Present this neutrally with no recommended/default option; leaving it blank (or choosing to list all) preserves the unfiltered fetch. Then run `scripts/fetch-numbers.sh <alias> <country> <phoneType> [searchParam]`, passing the area code / prefix as the optional fourth argument only when the user supplied one. Present the returned numbers as a numbered list and ask the user to select one — do not mark any number as recommended or default. If a narrowed fetch returns no numbers, tell the user and offer to retry with a different area code / prefix or to list all available numbers.
 
 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.
 

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

@@ -21,11 +21,18 @@ Query parameters:
 |-------|--------|-------|
 | `countryCode` | `US`, `CA` | |
 | `phoneNumberType` | `10DLC`, `Toll Free` | URL-encode the space in `Toll Free` as `%20` |
+| `searchParam` | area code (`10DLC`) or prefix (`Toll Free`) | **Optional.** Narrows results to numbers matching the area code / prefix. Omit to list all available numbers for the type. Passed through as-is (the API returns `400 BAD_REQUEST` on an invalid value). |
 
 ```bash
+# All available Toll Free numbers for US
 sf api request rest \
   "/services/data/v68.0/connect/number-management/v1/numbers?countryCode=US&phoneNumberType=Toll%20Free" \
   --target-org <alias>
+
+# Optional: narrow 10DLC numbers to a specific area code via searchParam
+sf api request rest \
+  "/services/data/v68.0/connect/number-management/v1/numbers?countryCode=US&phoneNumberType=10DLC&searchParam=415" \
+  --target-org <alias>
 ```
 
 Response:
@@ -42,10 +49,13 @@ Response:
 sf api request rest \
   "/services/data/v68.0/connect/number-management/v1/number" \
   --method POST \
-  --body '{"phoneNumberType":"Toll Free","country":"US","phoneNumber":"+14155551234"}' \
+  --body '{"phoneNumberType":"Toll Free","country":"US","phoneNumber":"+14155551234","contactCenterType":"Agentforce Contact Center"}' \
   --target-org <alias>
 ```
 
+`contactCenterType` is a fixed internal value (`Agentforce Contact Center`) — always sent,
+never gathered from the user.
+
 Success (`201`):
 
 ```json

package/skills/service-agentforce-contact-center-coordinate/scripts/fetch-numbers.sh

@@ -1,8 +1,11 @@
 #!/usr/bin/env bash
 # Fetch available default phone numbers for a country + phone-number type.
-# Usage: fetch-numbers.sh <org-alias> <country> <phone-type>
-#   country:    US | CA
-#   phone-type: 10DLC | "Toll Free"
+# Usage: fetch-numbers.sh <org-alias> <country> <phone-type> [search-param]
+#   country:      US | CA
+#   phone-type:   10DLC | "Toll Free"
+#   search-param: optional — area code (10DLC) or prefix (Toll Free) to narrow
+#                 results. Appended as the API's `searchParam` query param. Omit
+#                 (or pass empty) to list all available numbers for the type.
 # Output: JSON { "phoneNumbers": [...] } on stdout.
 
 set -euo pipefail
@@ -10,12 +13,15 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/lib.sh"
 
 if [[ "${1:-}" == "--help" || $# -lt 3 ]]; then
-  echo "Usage: fetch-numbers.sh <org-alias> <country> <phone-type>" >&2
+  echo "Usage: fetch-numbers.sh <org-alias> <country> <phone-type> [search-param]" >&2
   [[ "${1:-}" == "--help" ]] && exit 0 || exit 2
 fi
 
-ALIAS="$1"; COUNTRY="$2"; PHONE_TYPE="$3"
+ALIAS="$1"; COUNTRY="$2"; PHONE_TYPE="$3"; SEARCH_PARAM="${4:-}"
+
+QUERY="countryCode=${COUNTRY}&phoneNumberType=$(urlenc_spaces "$PHONE_TYPE")"
+[[ -n "$SEARCH_PARAM" ]] && QUERY="${QUERY}&searchParam=$(urlenc "$SEARCH_PARAM")"
 
 sf api request rest \
-  "/${NM_BASE}/numbers?countryCode=${COUNTRY}&phoneNumberType=$(urlenc_spaces "$PHONE_TYPE")" \
+  "/${NM_BASE}/numbers?${QUERY}" \
   --target-org "$ALIAS"

package/skills/service-agentforce-contact-center-coordinate/scripts/lib.sh

@@ -13,6 +13,22 @@ NM_BASE="services/data/${API_VERSION}/connect/number-management/v1"
 # URL-encode a value's spaces (sufficient for country/phoneType query params).
 urlenc_spaces() { printf '%s' "${1// /%20}"; }
 
+# Percent-encode a full value for safe use as a URL query-parameter value: only
+# the RFC 3986 unreserved set stays literal, everything else becomes %XX. Needed
+# for free-text values (e.g. a user-supplied area code / prefix) so reserved
+# characters like & or = can't inject extra query parameters into the request.
+urlenc() {
+  local s="$1" i c out=""
+  for (( i=0; i<${#s}; i++ )); do
+    c="${s:i:1}"
+    case "$c" in
+      [a-zA-Z0-9.~_-]) out+="$c" ;;
+      *) printf -v c '%%%02X' "'$c"; out+="$c" ;;
+    esac
+  done
+  printf '%s' "$out"
+}
+
 # XML-escape a value for safe interpolation into flow-template stringValue/label nodes.
 # Free-text org data (queue names, agent labels) can contain &, <, >, ", ' — unescaped
 # they produce malformed XML and an opaque `sf project deploy start` parse error.

package/skills/service-agentforce-contact-center-coordinate/scripts/procure-number.sh

@@ -14,8 +14,9 @@ fi
 
 ALIAS="$1"; COUNTRY="$2"; PHONE_TYPE="$3"; NUMBER="$4"
 
+# contactCenterType is a fixed internal value, not a user-supplied input.
 BODY=$(jq -n --arg t "$PHONE_TYPE" --arg c "$COUNTRY" --arg p "$NUMBER" \
-  '{phoneNumberType:$t, country:$c, phoneNumber:$p}')
+  '{phoneNumberType:$t, country:$c, phoneNumber:$p, contactCenterType:"Agentforce Contact Center"}')
 
 sf api request rest \
   "/${NM_BASE}/number" \

package/skills/service-concierge-portal-generate/references/portal-deploy-runbook.md

@@ -6,9 +6,9 @@ Help Portal deploys an **Agentforce Concierge experience** on an LWR Experience
 
 The agent script does **not** change here — this is channel/site metadata around the agent.
 
-## Execution model — headless with one operator pause
+## Execution model — Headless first, UI fallback
 
-Every step in §A–§S below is executed headlessly via `sf` CLI + Data API + Metadata API + Tooling API. There is exactly **one** step that requires the operator to click a Setup toggle: enabling the **Agentforce Orchestrator** OrgPerm (see §F.4). When the flow reaches that step, pause, present the operator with a direct Setup URL and clear instructions, and wait for them to reply `done` before continuing. Every other Setup-URL fallback in this document is a *last resort* — attempt the headless path first, and only fall back to UI if the headless path returns an unrecoverable error.
+Every step in §A–§S below is executed headlessly via `sf` CLI + Data API + Metadata API + Tooling API. The Agentforce Orchestrator OrgPerm (§F.4) is enabled via a Connect API POST — no operator UI pause is required. Every Setup-URL fallback in this document is a *last resort* — attempt the headless path first, and only fall back to UI if the headless path returns an unrecoverable error.
 
 If a non-critical step fails (branding polish, suggestion themes, progressive-rendering toggle), log the failure, continue, and surface the gap to the operator at the end. Do NOT abort the deploy for cosmetic gaps.
 
@@ -50,7 +50,7 @@ At the end of the run, print the live customer-facing portal URL for the operato
 > | 4 | Channel + routing + escalation | §E — `sf agent activate` first; if `MESSAGING_CHANNEL_DEV_NAME` not passed in, delegate to `service-digital-engagement-channel-configure` to create the channel (deploy XML with `<sessionHandlerType>AgentforceServiceAgent</sessionHandlerType>` + `<sessionHandlerQueue>` only — `sessionHandlerAsa` is not accepted by the v67 Metadata API); then delegate to `service-agentforce-channel-configure` (Phase 1: queue, Phase 2: Data API PATCH of `SessionHandlerId` + `FallbackQueueId` on the MessagingChannel, Phase 3: escalation question) | SOQL confirms `SessionHandlerId=$BOT_ID`, `FallbackQueueId` set; `BotVersion.Status=Active`; escalation answered by operator |
 > | 6 | Retrieve + edit + deploy bundle | §F.0 — retrieve `DigitalExperienceBundle:site/$BUNDLE_NAME`; **edit `sfdc_cms__brandingSet/*/content.json` with the four colors from §A (§D)**; replace home placeholder with 4 Concierge components (empty `attributes: {}`); add `Conversation__c` route + `conversation` view (§F.0.a); flip `authenticationType`; deploy | Retrieve confirms components + route; branding JSON contains user-specified hex values |
 > | 7 | Wire Concierge runtime binding | §F.3.a–d — create `EmbeddedServiceConfig` via Connect API `POST /connect/embeddedmessaging/deployment/setup` (same as Web Chat §C.4, omit `hostDomain`; auto-generates `ESW_*` site + test page), insert NSSE, **deploy AND assign** guest permset to Site's `GuestUserId` | `/webruntime/api/…/concierge/config` returns `deploymentName + siteUrl + scrtUrl` **AND** `SELECT PermissionSet.Name FROM PermissionSetAssignment WHERE AssigneeId=<GuestUserId>` returns the `<Bundle>_Guest_Concierge` row |
-> | 8 | **⏸ Enable Agentforce Orchestrator (operator pause)** | §F.4 — preflight SOQL on `AgenticCtxtDecorDefinition`; if not supported, pause and ask operator to flip the toggle at the printed Setup URL; wait for `done` reply; then `POST /connect/self-service/setup/agentOrchestrator {name, developerName, agentId}` | Connect GET returns orchestrator with agentId |
+> | 8 | Enable Agentforce Orchestrator + create orchestrator binding | §F.4 — `POST /connect/self-service/setup/agentforceOrchestratorEnablement?includeAgentforceOrchestratorPerms=false` (headless, no operator pause); verify SOQL probe; then `POST /connect/self-service/setup/agentOrchestrator {name, developerName, agentId}` | Connect GET returns orchestrator with agentId |
 > | 9 | Deploy the bundle | §G — `sf project deploy start -m DigitalExperienceBundle:site/$BUNDLE_NAME` | Status: Succeeded |
 > | 10 | Publish the site | §I — `POST /connect/communities/$NETWORK_ID/publish`; PATCH `Network.Status=Live` | Site loads at `PUBLISHED_PORTAL_URL` |
 > | 11 | Network guest flags | §L.0 — PATCH `Network.OptionsGuestChatterEnabled=true AND OptionsGuestMemberVisibility=true` (single Data API call). ALSO verify auth ESC `AreGuestUsersAllowed=true` — flip via mdapi + republish if false. | `/concierge/config?asGuest=true` returns 200; SOQL confirms both Network flags + ESC flag true |
@@ -712,13 +712,13 @@ curl -sS "$PUBLISHED_PORTAL_URL/webruntime/api/services/data/v67.0/connect/self-
 
 All three fields must be non-null. If `deploymentName` is null, the bound ESC references a different site or MessagingChannel — verify the `<site>` in the ESC metadata is the LWR site (F.3.a).
 
-### F.4 — Wire the Agentforce Orchestrator *(one operator pause, then fully headless)*
+### F.4 — Wire the Agentforce Orchestrator *(Headless first, UI fallback)*
 
-The Agentforce Orchestrator provides the personalized greeting, Action/Object recommendations, and Concierge proactive routing. The "Enable Agentforce Orchestrator" OrgPerm gates the agent-binding surfaces (Connect POST, Data API sObject, SOQL). Detect the toggle state with a SOQL write-probe, prompt one manual click if off, then continue fully headless.
+The Agentforce Orchestrator provides the personalized greeting, Action/Object recommendations, and Concierge proactive routing. The "Enable Agentforce Orchestrator" OrgPerm gates the agent-binding surfaces (Connect POST, Data API sObject, SOQL). Enable it headlessly via `POST /connect/self-service/setup/agentforceOrchestratorEnablement`, verify with the SOQL probe, then create the orchestrator binding.
 
 **F.4.0 — Detection preflight.**
 
-Run the probe up to **2 times** before concluding the toggle is off. The `sf` CLI occasionally mixes warning output into stdout on the first call, which causes a false "not supported" parse. Re-running the identical query without waiting resolves the issue — no org state changes between attempts.
+Run the SOQL probe up to **2 times** before concluding the toggle is off. The `sf` CLI occasionally mixes warning output into stdout on the first call causing a false "not supported" parse. Re-running the identical query without waiting resolves the issue — no org state changes between attempts.
 
 ```bash
 TOGGLE_STATE="UNKNOWN"
@@ -735,11 +735,24 @@ done
 ```
 
 - ✅ `TOGGLE_STATE=ON` → proceed with §F.4.2.
-- ❌ `TOGGLE_STATE=OFF` (both attempts) → toggle is genuinely OFF, **pause and prompt the operator**.
+- ❌ `TOGGLE_STATE=OFF` (both attempts) → toggle is genuinely OFF → proceed to §F.4.1 (headless enable).
 
-**F.4.1 — ⏸ OPERATOR PAUSE: enable the Orchestrator OrgPerm.**
+**F.4.1 — Headless enable via Connect API (fully headless — no operator pause).**
 
-If the SOQL probe returned "not supported", send this message verbatim to the operator, then wait for their reply:
+Enable Agentforce Orchestrator headlessly:
+
+> **`min_api_version: 68.0`** — this endpoint is only available on API v68.0+. On v67 orgs the POST returns `NOT_FOUND`; fall through to the UI path below.
+
+```bash
+sf api request rest -o "$ORG" --method POST \
+  "/services/data/v68.0/connect/self-service/setup/agentforceOrchestratorEnablement?includeAgentforceOrchestratorPerms=false" \
+  --body '{}'
+# → {"isSuccess": true}
+```
+
+After the POST, re-run the §F.4.0 SOQL probe to confirm `TOGGLE_STATE=ON`. If the probe still returns "not supported" after a successful POST (can happen on a slow pod), wait 10 seconds and re-probe once more. If the probe is still off after that re-probe, fall back to the UI step below — do not continue to §F.4.2.
+
+If the org **genuinely does not have this surface** (the POST itself returns `NOT_FOUND` or `UNSUPPORTED_OPERATION`), fall through to the legacy UI path as a last resort:
 
 > **One manual step needed.** Please open this URL and enable Agentforce Orchestrator:
 >
@@ -749,7 +762,7 @@ If the SOQL probe returned "not supported", send this message verbatim to the op
 > 2. Wait for the confirmation banner.
 > 3. Reply `done` here and I'll continue.
 
-When the operator replies `done`, re-run the F.4.0 SOQL probe. If it still returns "not supported", either the toggle wasn't flipped or there's an org-shape gap. Ask them to double-check, then re-probe. If the org genuinely does not have this surface (older-API pod), fall through to the F.4 skip: continue the deploy without the Orchestrator, and log the gap in the operator handoff.
+If the org cannot enable this at all, skip §F.4 entirely and log the gap in the operator handoff.
 
 **F.4.2 — Bot prerequisite check.**
 
@@ -1419,7 +1432,7 @@ sf org open --target-org $ORG --path "/<url-path>/"
 | Guest curl to `/webruntime/api/.../connect/self-service/*` returns `HTTP 401 UNAUTHORIZED` | `Network.OptionsGuestChatterEnabled = False` on target | Run §L.0 diagnostic; PATCH to True via Data API — no republish required |
 | Portal loads, `/concierge/config` returns 200, prompt bar renders but says **"Agents are not available. Try again later."** | Bot-routing wiring missing. Typical gaps: `PresenceUserConfigUser`, `GroupMember`, `Group.QueueRoutingConfigId` | Run §N — three Data-API writes |
 | §N writes all succeed but chat *still* shows "Agents are not available" immediately | Automated-Process pickup path needs to spin up after routing wiring changes | Re-activate the BotVersion via CLI (`sf agent deactivate` + `sf agent activate`). Wait a few minutes. Do NOT rely on `UserServicePresence` COUNT as the readiness signal |
-| Prompt bar responses are ungrounded / navigate to `/error` on newer-API orgs | Agentforce Orchestrator not wired | See §F.4 — enable the OrgPerm (operator pause) then `POST /connect/self-service/setup/agentOrchestrator` |
+| Prompt bar responses are ungrounded / navigate to `/error` on newer-API orgs | Agentforce Orchestrator not wired | See §F.4 — `POST /connect/self-service/setup/agentforceOrchestratorEnablement?includeAgentforceOrchestratorPerms=false`, verify SOQL probe, then `POST /connect/self-service/setup/agentOrchestrator` |
 | Agentforce Orchestrator's "Add Tool → Agent" picker is empty | `BotDefinition.AgentTemplate` is `null` — Bot was created via headless Metadata deploy, not the Setup wizard | Delete the Bot and recreate via Setup → Agentforce Agents → New Agent → From Template → Agentforce Service Agent |
 
 ---

package/skills/service-digital-engagement-channel-configure/SKILL.md

@@ -28,9 +28,18 @@ Creates `MessagingChannel` metadata XML for Salesforce Messaging for In-App and
 
 ---
 
+## Entry points and transport
+
+- **Delegated** (`context.calledFrom == "service-onboarding"`): use the approved `values`, ask nothing, and return `failed` naming any missing required key. **Standalone** (no `context`): run Clarifying Questions.
+- **Transport A** (primary): headless-360 MCP `dispatch` / `dispatch_readonly` on `/headless/metadata`. **Transport B**: the `sf` commands below, only where a probe shows Transport A unavailable.
+
+Details: `references/onboarding_contract.md` (§1 entry points, §2 transport, §3 pre-scan, §5 result).
+
+---
+
 ## Clarifying Questions
 
-Before generating, ask the user if not already clear:
+Before generating, ask the user if not already clear (standalone only):
 
 - What is the channel name / label? (used for `masterLabel` and file name)
 - What routing type? (Omni-Channel Flow, Omni-Channel Queue, User, or Agentforce Service Agent)
@@ -80,19 +89,21 @@ All steps are sequential. Do not skip or reorder.
 
 1. **Verify org API version** — run `scripts/check-api-version.sh 67.0 <org-alias>` and report any errors it returns. If the script fails, generate a `sfdx-project.json` in the metadata output folder with `"sourceApiVersion": "67.0"`.
 
-2. **Collect inputs** — confirm the channel label, routing type, routing target, and verification settings from the user per Clarifying Questions above.
+2. **Collect inputs** — standalone: per Clarifying Questions. Delegated: from `values`. Then probe transport with a read-only `GET` of `MessagingChannel` (contract §2).
 
 3. **Determine file name** — run `scripts/normalize-channel-name.sh "<LABEL>"` and surface any errors it returns.
 
-4. **Verify routing target exists** — query the org to confirm the referenced routing target exists:
+3a. **Pre-scan** — `GET` `MessagingChannel` by the step 3 name (contract §3): none → create; matches and active → no write, `already-configured`, skip to Phase 4; matches but inactive → activate only (step 15); differs → announce each change, then write the full document (standalone: ask first).
+
+4. **Verify routing target exists** — skip when step 3a ended in `already-configured` or activate-only, so a re-run never creates a queue. Query the org to confirm the referenced routing target exists:
    - For Queue: `sf data query --query "SELECT Id, DeveloperName FROM Group WHERE Type='Queue' AND DeveloperName='<QUEUE_NAME>'" --target-org <org-alias>`
    - For Flow: `sf data query --query "SELECT Id, ApiName FROM FlowDefinitionView WHERE ApiName='<FLOW_NAME>' AND IsActive=true" --target-org <org-alias>`
    - For User: `sf data query --query "SELECT Id, Username FROM User WHERE Id='<USER_ID>' AND IsActive=true" --target-org <org-alias>`
    - For ASA: `sf data query --query "SELECT Id, DeveloperName FROM BotDefinition WHERE DeveloperName='<BOT_NAME>'" --target-org <org-alias>`
    - Also verify the fallback queue exists (required for Flow, User, and ASA routing)
    
-   If any target is not found, inform the user and ask whether to create it. If the user confirms:
-   - For Queue: generate a `.queue-meta.xml` with `MessagingSession` as the `queueSobject` type and deploy it before the channel. **A new queue is unusable for routing without a `QueueRoutingConfig` — a channel deployed against a queue with none fails at session-start with "Agents are not available. Try again later," even though the channel itself deploys and activates cleanly.** Immediately after the queue deploys, resolve or create its routing config by following `service-agentforce-channel-configure`'s `references/queue-resolution.md` Step 4 — do not defer this to a later skill invocation, since this may be the only place a newly created queue is ever touched.
+   If any target is not found: standalone — inform the user and ask whether to create it. Delegated — return `failed` naming the missing target; never create it. If the standalone user confirms creating:
+   - For Queue: generate a `.queue-meta.xml` with `MessagingSession` as the `queueSobject` type and deploy it before the channel. **A new queue needs a `QueueRoutingConfig`, or sessions fail with "Agents are not available. Try again later" even though the channel deploys and activates.** Right after the queue deploys, resolve or create one per `service-agentforce-channel-configure`'s `references/queue-resolution.md` Step 4 — do not defer it.
    - For Flow/User/ASA: inform the user that the flow, user, or bot must be created separately (out of scope for this skill)
 
 5. **Read the channel settings reference** — load `references/channel_settings.md` to understand all available configuration options and their valid values.
@@ -110,10 +121,7 @@ All steps are sequential. Do not skip or reorder.
    | User | `User` | `sessionHandlerUser` + `sessionHandlerQueue` (fallback) |
    | Agentforce Service Agent | `AgentforceServiceAgent` | `sessionHandlerQueue` (fallback) + `sessionHandlerAsa` (bot dev name — required, see v67 note below) |
 
-   > **v67 note — `<sessionHandlerAsa>` is required in the XML, not rejected.** Confirmed on a v67.0 org: omitting `<sessionHandlerAsa>` causes the deploy to fail with "Missing required Agentforce Service Agent." Include it and the deploy binds `SessionHandlerId` automatically — no post-deploy Data API PATCH needed.
-   > 1. **Verify the bot is Active before channel creation.** The Metadata API rejects binding with "Only active Agentforce Service Agents are supported." Run `sf agent activate -o <org> --api-name <BotDevName>` and confirm `BotVersion.Status = Active` first.
-   > 2. Deploy the XML with `<sessionHandlerType>AgentforceServiceAgent</sessionHandlerType>`, `<sessionHandlerQueue>` (fallback), and `<sessionHandlerAsa>{BotDevName}</sessionHandlerAsa>`.
-   > 3. Verify: `sf data query -o <org> -q "SELECT SessionHandlerId, FallbackQueueId FROM MessagingChannel WHERE DeveloperName='<ChannelDevName>'" --json` — both must be non-null after the deploy, with no separate PATCH step.
+   > **v67 note — `<sessionHandlerAsa>` is required** (omitting it fails with "Missing required Agentforce Service Agent"); the deploy then binds `SessionHandlerId`, no PATCH needed. The bot must be Active first: run `sf agent activate -o <org> --api-name <BotDevName>` and confirm `BotVersion.Status = Active`.
 
 8. **Apply user verification** — if enabled, set `embeddedConfig.authMode` to `Auth` and include `<messagingAuthorizations>`. If not enabled, set `embeddedConfig.authMode` to `UnAuth` and omit `<messagingAuthorizations>`.
 
@@ -142,21 +150,21 @@ All steps are sequential. Do not skip or reorder.
 
 ### Phase 3 — Deploy and Activate
 
-14. **Deploy the channel** — deploy the generated `.messagingChannel-meta.xml` file to the target org:
+14. **Write the channel** — Transport A: `POST` to create, `PUT` the **full** document to update (a minimal PUT drops `embeddedConfig`); check `results[].success`, then re-`GET`. Transport B:
     ```bash
     sf project deploy start --source-dir <path-to-messagingChannels-folder> --target-org <org-alias>
     ```
 
-15a. **ASA routing only — verify the bind landed.** Skip this step for Queue, Flow, and User routing types. Because `<sessionHandlerAsa>` was included in the deployed XML (step 7), the deploy itself binds `SessionHandlerId` — no separate Data API PATCH is needed.
+15a. **ASA routing only — verify the bind landed** (skip for Queue, Flow, User):
 
     ```bash
     sf data query -o <org> --json \
       -q "SELECT SessionHandlerId, FallbackQueueId FROM MessagingChannel WHERE DeveloperName='<CHANNEL_DEV_NAME>'"
     ```
 
-    Both `SessionHandlerId` and `FallbackQueueId` must be non-null. If either is null, confirm `<sessionHandlerAsa>` and `<sessionHandlerQueue>` were both present in the deployed XML and that the bot was Active before the deploy.
+    Both must be non-null; if not, check both handler elements were in the XML and the bot was Active before the deploy.
 
-15. **Activate the channel** — after successful deployment, activate the messaging channel:
+15. **Activate the channel** — after a successful write, activate the messaging channel (`IsActive` is not part of the metadata). Transport A: sObject update `{"IsActive": true}` through `dispatch`. Transport B:
     ```bash
     sf data update record --sobject MessagingChannel --where "DeveloperName='<CHANNEL_NAME>'" --values "IsActive=true" --target-org <org-alias>
     ```
@@ -165,7 +173,9 @@ All steps are sequential. Do not skip or reorder.
 
 16. **Verify against checklist** — confirm all items in the Verification Checklist below pass before presenting output.
 
-17. **Present output** — show the generated file to the user with a summary of configured settings and confirm activation status. Offer next steps:
+17. **Report** — delegated: return the contract §5 result and stop. Standalone: continue.
+
+18. **Present output** (standalone) — show the generated file to the user with a summary of configured settings and confirm activation status. Offer next steps:
     - **Automated responses** — ask if the user wants to configure `<automatedResponses>` (OptOutConfirmation, HelpResponse). If yes, generate elements with `autoResponseContentType: TextResponse`, `language`, and XML-escaped `response` text, then redeploy.
 
 ---
@@ -278,6 +288,7 @@ File structure follows the template in `assets/messaging_channel_template.xml`.
 
 | File | When to read |
 |------|-------------|
+| `references/onboarding_contract.md` | Delegated mode (`context.calledFrom == "service-onboarding"`), org writes (transport), module registration |
 | `assets/messaging_channel_template.xml` | Before generating — use as the starting structure |
 | `references/channel_settings.md` | When configuring channel options beyond defaults |
 | `scripts/check-api-version.sh` | Phase 1 — verify org API version meets the passed minimum (67.0) |