@salesforce/afv-skills 1.65.1 → 1.67.0

package/skills/platform-widget-generate/references/widget-formulas.md

@@ -17,6 +17,7 @@ Every formula expression is wrapped in `{!...}`, similar to a plain binding:
 - Functions and operators are case-sensitive UPPERCASE.
 - A formula can nest functions and mix functions with operators: `{!TEXT(ROUND($attrs.property, 2))}`, `{!LEFT($attrs.property, 5) & "..."}`.
 - A formula-bearing attribute is still bound to schema properties the same way as a plain binding — every `$attrs.X` / `$item.X` referenced inside a formula must resolve to a real schema property or loop variable, per the `bindings-resolve` self-validation check.
+- A Custom Label reference `$Label.c.<LabelName>` can be used as a text value inside a formula. See `references/widget-labels.md`.
 
 ---
 
@@ -34,7 +35,7 @@ Only the operators/functions listed here are confirmed supported — do not inve
 | `/` | Divide | `$attrs.operand1 / $attrs.operand2` |
 | `^` | Exponent | `$attrs.operand1 ^ $attrs.operand2` |
 
-Standard precedence applies (`^` > `*`/`/` > `+`/`-`); parenthesize to be explicit, especially when combining multiple arithmetic operators.
+Unary minus (`-$attrs.fieldName`) is also supported. Precedence, lowest to highest: `||`, `&&`, equality, relational, `+` `-` `&`, `^`, `*` `/`, unary. Note that `*` and `/` bind tighter than `^`, so `2 * 3 ^ 2` is `(2 * 3) ^ 2`; parenthesize to be explicit.
 
 ### 2. Comparison operators
 
@@ -47,36 +48,40 @@ Return `true`/`false`; commonly used inside `IF()` or `meta.if`.
 | `>` / `<` | Greater / less than | `$attrs.property > 1000`               |
 | `>=` / `<=` | Greater-or-equal / less-or-equal | `$attrs.property1 >= $attrs.property2` |
 
+`==` and `!=` are accepted as aliases for `=` and `<>`. Both operands must have the same type; text is never compared with a number.
+
 ### 3. Logical functions
 
 | Function | Description | Example                                                                                              |
 |---|---|------------------------------------------------------------------------------------------------------|
-| `IF(cond, then, else)` | Conditional value; nests for multi-branch logic | `IF($attrs.property > value, 'result1', 'result2')`                                                  |
+| `IF(cond, then, else)` | Conditional value; nests for multi-branch logic. `cond` must be a boolean (`IF($attrs.count > 0, …)`, not `IF($attrs.count, …)`) and both branches must have the same type | `IF($attrs.property > value, 'result1', 'result2')`                                                  |
 | `CASE(expr, val1, res1, val2, res2, ..., default)` | Multi-way match, cleaner than nested `IF` for 3+ branches | `CASE($attrs.property, 'value1', 'result1', 'value2', 'result2', 'value3', 'result3', 'defaultResult')` |
 | `AND(...)` | All conditions true | `AND($attrs.property1, $attrs.property2 > value)`                                                    |
 | `OR(...)` | Any condition true | `OR($attrs.property1, $attrs.property2 > value)`                                                     |
 | `NOT(val)` | Negate a boolean | `NOT($attrs.property)`                                                                               |
-| `ISNULL(val)` | True if the value is null | `IF(ISNULL($attrs.property), 'null', 'has-value')`                                                   |
+| `&&` / `\|\|` / `!` (operators) | Aliases for `AND` / `OR` / `NOT` | `$attrs.property1 && !$attrs.property2` |
+| `ISNULL(val)` | True if the value is null. Always false for text — use `ISBLANK` for strings | `IF(ISNULL($attrs.property), 'null', 'has-value')`                                                   |
 | `ISBLANK(val)` | True if null or empty string | `IF(ISBLANK($attrs.property), 'blank', 'has-value')`                                                 |
 
 ### 4. Text functions
 
 | Function | Description | Example                                             |
 |---|---|-----------------------------------------------------|
-| `UPPER(str)` / `LOWER(str)` | Case conversion | `UPPER($attrs.property)`                            |
+| `UPPER(str[, locale])` / `LOWER(str[, locale])` | Case conversion, optionally for a locale such as `'tr'` | `UPPER($attrs.property)`                            |
 | `LEFT(str, n)` / `RIGHT(str, n)` | First/last `n` characters | `LEFT($attrs.property, 3)`                          |
 | `MID(str, start, len)` | Substring, **1-based** start index (first character is position 1, not 0) | `MID($attrs.property, 1, 3)`                        |
+| `SUBSTR(str, start[, len])` | Substring with a **1-based** start; a negative `start` counts from the end; without `len`, runs to the end | `SUBSTR($attrs.property, -4)` |
 | `LEN(val)` | Length of a string | `LEN($attrs.property)`                              |
 | `TRIM(str)` | Strip leading/trailing whitespace | `TRIM($attrs.property)`                             |
 | `REVERSE(str)` | Reverse a string | `REVERSE($attrs.property)`                          |
 | `SUBSTITUTE(str, old, new)` | Replace all occurrences | `SUBSTITUTE($attrs.property, 'string1', 'string2')` |
-| `FIND(search, str)` | 1-based index of `search` in `str`, or falsy if absent | `FIND('string', $attrs.property)`                   |
+| `FIND(search, str[, start])` | 1-based index of `search` in `str`, or `0` if absent; optional 1-based `start` position | `FIND('string', $attrs.property)`                   |
 | `LPAD(str, len, pad)` / `RPAD(str, len, pad)` | Pad to a fixed width | `LPAD($attrs.property, 12, '.')`                    |
 | `TEXT(val)` | Coerce a non-string value to text (commonly paired with `ROUND`) | `TEXT(ROUND($attrs.property, 2))`                   |
 | `VALUE(str)` | Parse text to a number (inverse of `TEXT`) | `VALUE($attrs.property)`                            |
 | `CONTAINS(str, sub)` | String contains substring — boolean, pair with `IF` | `CONTAINS($attrs.property, 'string')`               |
 | `BEGINS(str, prefix)` | String starts with — boolean, pair with `IF` | `BEGINS($attrs.property, 'string')`                 |
-| `&` (operator) | Concatenate strings | `$attrs.property1 & ' — ' & $attrs.property2`       |
+| `&` (operator) | Concatenate strings. Both sides must be text, so wrap numbers and dates in `TEXT()` — `'Total: ' & TEXT($attrs.total)` | `$attrs.property1 & ' — ' & $attrs.property2`       |
 
 ### 5. Math functions
 
@@ -99,7 +104,7 @@ Return `true`/`false`; commonly used inside `IF()` or `meta.if`.
 | `DAY(date)` / `MONTH(date)` / `YEAR(date)` | Extract date components | `DAY(DATEVALUE($attrs.fieldName))`              |
 | `WEEKDAY(date)` | Day of week, `1`=Sunday … `7`=Saturday | `WEEKDAY(DATEVALUE($attrs.fieldName))`      |
 | `ADDMONTHS(date, n)` | Add `n` whole months to a date | `ADDMONTHS(DATEVALUE($attrs.fieldName), 3)` |
-| `TODAY()` / `NOW()` / `TIMENOW()` | Current server date / datetime / time — no arguments | `TODAY()`                                       |
+| `TODAY()` / `NOW()` / `TIMENOW()` | Current date / datetime / time in UTC — no arguments | `TODAY()`                                       |
 | `DATE(year, month, day)` | Construct a date literal | `DATE(2026, 12, 31)`                            |
 | `HOUR(dt)` / `MINUTE(dt)` / `SECOND(dt)` / `MILLISECOND(dt)` | Extract time components from a datetime | `HOUR(NOW())`                                   |
 
@@ -121,3 +126,15 @@ A raw date/datetime **string** attribute (e.g. an ISO string from `$attrs`) must
 | `ISNUMBER(val)` | True if the value parses as a number | `ISNUMBER($attrs.fieldName)` |
 | `REGEX(str, pattern)` | True if `str` matches the regex `pattern` (standard regex string) | `REGEX($attrs.fieldName, '^[A-Z]{2} [0-9]+$')` |
 
+### 9. Locale formatting functions
+
+Format values for the viewer's locale. A null or blank input returns null. The optional last argument is a decimal count for the number functions and `'short'` (default), `'medium'` or `'long'` for the date and time functions.
+
+| Function | Description | Example |
+|---|---|---|
+| `FORMATNUMBER(num[, decimals])` | Locale-formatted number | `FORMATNUMBER($attrs.fieldName, 2)` |
+| `FORMATPERCENT(num[, decimals])` | Locale-formatted percent (`0.25` → `25%`) | `FORMATPERCENT($attrs.fieldName, 1)` |
+| `FORMATCURRENCY(num)` | Currency code followed by the amount, e.g. `USD 1,234.50` (no currency symbol) | `FORMATCURRENCY($attrs.fieldName)` |
+| `FORMATDATE(date[, style])` | Locale date | `FORMATDATE($attrs.fieldName, 'medium')` |
+| `FORMATDATETIME(dt[, style])` | Locale date and time | `FORMATDATETIME($attrs.fieldName, 'long')` |
+| `FORMATTIME(time[, style])` | Locale time | `FORMATTIME($attrs.fieldName)` |

package/skills/platform-widget-generate/references/widget-gotchas.md

@@ -0,0 +1,10 @@
+# Widget Generation 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                                                                                                                                                                     |
+| 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 SKILL.md *Actions*)                                                                                                                                             |
+| 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                                                                                               |

package/skills/platform-widget-generate/references/widget-labels.md

@@ -0,0 +1,78 @@
+# Widget Localization with Custom Labels
+
+A widget shows translated text by referencing a Salesforce Custom Label instead of a hardcoded string.
+
+---
+
+## Syntax
+
+```text
+{!$Label.c.<LabelName>}
+```
+
+- `c` is the org's default namespace. Always write it.
+- The label name is static. Never build it from data — `{!$Label.c.$attrs.key}` can't be validated when the widget is saved.
+- A `$Label` reference is not a `$attrs` binding and has no entry in `schema.json`.
+
+---
+
+## What to localize
+
+Replace every static, user-visible string in an allowed attribute, unless the user limited the request to specific strings.
+
+**Allowed**
+
+- Display text: `text`, `label`, `placeholder`, `title`, and other free-form string attributes (per `getUiComponentSchemas`)
+- Text results inside a formula, e.g. the branches of an `IF` or `CASE`
+
+**Not allowed**
+
+- `meta` directives (`if`, `forEach`, `forItem`)
+- Enum-valued attributes (`variant`, `size`, `color`, `gap`, `align`, `justify`) and icon names
+- Anything inside `actions` (`url`, `target`, `sendMessage` `content`)
+- Data bound with `$attrs` / `$item` — payload values are not translated
+- `schema.json` and the `-meta.xml`
+
+---
+
+## Label names
+
+Reuse existing labels first. If the user names labels, or the project's CustomLabels file (`labels/CustomLabels.labels-meta.xml`) already has a label whose value matches the text, reference that label's `fullName` verbatim. Otherwise propose `<WidgetName>_<Role>`.
+
+---
+
+## Combining labels with data
+
+- Join a label and data with `&` (see `references/widget-formulas.md`):
+  `"text": "{!$Label.c.<LabelName> & ' ' & TEXT($attrs.<attrName>)}"`
+- Choose between labels with `IF` / `CASE`:
+  `"label": "{!IF($attrs.<booleanAttr>, $Label.c.<LabelWhenTrue>, $Label.c.<LabelWhenFalse>)}"`
+
+---
+
+## Creating labels
+
+This skill gives no guidance on authoring label metadata, and the widget is complete without it. Create labels only when the user asks you to. When you do, add them to the project's existing CustomLabels file instead of overwriting it, and never redefine a label that already exists. The user is responsible for checking the labels and any translations in the org and for deploying them with or before the widget.
+
+---
+
+## Label report
+
+End the response with this report:
+
+```markdown
+### Custom Labels used by this widget
+
+These labels must exist in the target org before you deploy — deploying a widget that references a missing label fails.
+
+| Label name | Value (default language) | Status | Used in |
+|---|---|---|---|
+| OrderStatus_Heading | Order status | Existing | `tile/text` `text` (widget heading) |
+| OrderStatus_TrackButton | Track order | To create | `tile/button` `label` |
+```
+
+- List each distinct label once, in the order it first appears in the widget.
+- **Label name** is the `fullName`, without the `c.` prefix.
+- **Value** is the literal text the label replaced.
+- **Status** is `Existing` (already in the project or named by the user), `Created` (you wrote it), or `To create` (the user must create it).
+- **Used in** names the block definition and attribute.

package/skills/platform-widget-generate/references/widget-styling.md

@@ -0,0 +1,12 @@
+# Widget Styling Best Practices
+
+Widgets express *intent*, not pixels. Each surface provides a default look and feel; brand/theme overrides apply automatically.
+
+- **Style semantically.** Use `variant`, `size`, and other enum-typed attributes (`primary`, `destructive`, `success`, `warning`). Do not pin literal colors or pixel values.
+- **One primary action per visible group.** At most one `tile/button` with `variant: primary`. Use `secondary` or `destructive` for additional actions (see the `tile/button` schema for the full variant enum).
+- **Every `tile/button` needs a `click` action.** See SKILL.md *Actions* — an action-less button renders disabled.
+- **One `h1` per widget.** Use `h2`/`h3` for sub-section headings, `body` for prose, `caption` for helper text.
+- **Use semantic state variants on state-bearing blocks** (`tile/badge`, `tile/callout`).
+- **Omit attributes that equal the schema default.** Check each property's `default` in the `getUiComponentSchemas` metadata (step 4). If the value you would write matches it — e.g. `gap`, `size`, or `action/openLink` `target: "_blank"` — leave the attribute out. Set an attribute only to change it.
+- **Don't pin `width`** unless a content constraint requires it.
+- **Use the Lucide icon set.** Pass the Lucide name (`"check"`, `"alert-circle"`); other icon libraries are not supported.

package/skills/sales-call-scoring-configure/SKILL.md

@@ -146,12 +146,19 @@ Classify the org into one of 4 states:
 ### Phase 3 — Prerequisite enablement (State 2 only)
 
 - **License gate (checked first):** query `OrganizationSettingsDetail`
-  (Tooling API) for the `ECICallScoringAI` OrgPermission. If it isn't
-  `true`, exit with: "AI call coaching is not available in this org and org
-  requires Agentforce for Sales license." Non-zero exit. This runs even
-  when `enableCallCoaching`/`enableECICallScoring` already read favorably,
-  since those settings don't by themselves confirm the org is licensed.
-  **Must run before the ECI-off check below** — a genuinely unlicensed org
+  (Tooling API) for the `ECICallScoringAI` OrgPermission. Only an **explicit
+  `false`** refuses — exit with: "AI call coaching is not available in this
+  org and org requires Agentforce for Sales license." (Non-zero exit.) If the
+  permission **can't be read** — the query is rejected with `INVALID_TYPE`
+  (some org editions, for example Developer Edition) or returns no row — treat
+  it as **unknown and proceed**; do NOT fail closed on an unreadable signal.
+  The Einstein GenAI `TYPE_UNAVAILABLE` pre-check catches most unlicensed
+  orgs; the enable `updateMetadata` write is the final check. This mirrors the Phase 0
+  `ConversationPilot` gate, which defers on any non-conclusive read.
+  This runs even when `enableCallCoaching`/`enableECICallScoring`
+  already read favorably, since those settings don't by themselves confirm the
+  org is licensed. **Must run before the ECI-off check below** — a genuinely
+  unlicensed org
   and a licensed-but-toggled-off org both read `enableCallCoaching=false`,
   so checking ECI first would misdiagnose a licensing gap as a self-serve
   Setup toggle (the regression the `NoLicense` eval dataset guards against).
@@ -217,7 +224,7 @@ Re-read `enableECICallScoring`. Require `true`. Print SOAP response on failure.
   is server-side read-only and `updateMetadata` returns
   `INSUFFICIENT_ACCESS_OR_READONLY`. `enable-call-scoring.sh` maps this to a
   transient "still finishing turning on — wait a few minutes and re-run"
-  message rather than a terminal failure (W-23968462).
+  message rather than a terminal failure.
 - **Every SOAP call is bounded by a 30s timeout** (`CURL_TIMEOUT` in
   `enable-call-scoring.sh`, matching the only existing timeout precedent in
   this repo — the Pipeline skill's `setup-all.sh`) and classified via
@@ -243,14 +250,14 @@ Re-read `enableECICallScoring`. Require `true`. Print SOAP response on failure.
 - **SOAP helpers**: `scripts/shared/soap.sh` (copied from the Pipeline skill —
   `redact_token`, `parse_soap_response`)
 - **Server-side gate** (declarative access check):
-  `core/conversation-udd/java/resources/udd/conversation-udd/ConversationalIntelligence.accessChecks.xml`
+  `ConversationalIntelligence.accessChecks.xml`
   — `orgHasCallScoring` = ECI arm OR River Rush arm; `orgHasECICallScoringWithAI`
   adds Einstein GenAI + `ECICallScoringAI` license perm on top.
 - **Pref declaration**:
-  `core/conversation-udd/java/resources/udd/conversation-udd/ConversationalIntelligence.settings.xml`
+  `ConversationalIntelligence.settings.xml`
   — `<orgPreference name="ECICallScoringEnabled" mdApiName="enableECICallScoring" ...>`
 - **Java feature registration** (would be the entry point if a
-  SetupDiscoveryService REST/MCP wrapper existed): `core/conversation-impl/java/src/conversation/features/CoachingCompetenciesFeature.java`
+  SetupDiscoveryService REST/MCP wrapper existed): `CoachingCompetenciesFeature.java`
 
 ## Competency CRUD workflow
 

package/skills/sales-call-scoring-configure/scripts/enable-call-scoring.sh

@@ -61,14 +61,14 @@ resolve_org_auth_with_token "$ORG_ALIAS" || exit 1
 # orgs) reject the OrganizationSettingsDetail query with INVALID_TYPE. That's
 # not a licensing signal — it's a metadata-availability signal. Treat any
 # non-conclusive result as "unknown, defer to SOAP" and only refuse when the
-# query explicitly comes back "false" (W-24022554).
+# query explicitly comes back "false".
 CONVERSATIONPILOT_ENABLED=""
 if CONVERSATIONPILOT_RAW=$(sf data query --target-org "$ORG_ALIAS" --use-tooling-api \
     --query "SELECT SettingValue FROM OrganizationSettingsDetail WHERE SettingName='ConversationPilot' AND DataType='OrgPermissionSettings'" \
     --json 2>/dev/null); then
   CONVERSATIONPILOT_JSON=$(echo "$CONVERSATIONPILOT_RAW" | awk '/^{/,EOF')
   if echo "$CONVERSATIONPILOT_JSON" | jq -e '.status == 0' >/dev/null 2>&1; then
-    CONVERSATIONPILOT_ENABLED=$(echo "$CONVERSATIONPILOT_JSON" | jq -r '.result.records[0].SettingValue // empty')
+    CONVERSATIONPILOT_ENABLED=$(echo "$CONVERSATIONPILOT_JSON" | jq -r '.result.records[0].SettingValue | select(. != null)')
   fi
 fi
 
@@ -215,7 +215,6 @@ fi
 # doing a write — Einstein GenAI Platform is a hard prerequisite for AI
 # Call Scoring, so an org that can't even see that settings type won't be
 # able to enable Call Coaching regardless of what the ECI toggle says.
-# W-24026047.
 #
 # Not perfect: an org could have the GenAI platform present but still lack
 # the specific Call Scoring license. State 2c's ECICallScoringAI
@@ -245,19 +244,33 @@ if ECICALLSCORINGAI_RAW=$(sf data query --target-org "$ORG_ALIAS" --use-tooling-
     --json 2>/dev/null); then
   ECICALLSCORINGAI_JSON=$(echo "$ECICALLSCORINGAI_RAW" | awk '/^{/,EOF')
   if echo "$ECICALLSCORINGAI_JSON" | jq -e '.status == 0' >/dev/null 2>&1; then
-    ECICALLSCORINGAI_ENABLED=$(echo "$ECICALLSCORINGAI_JSON" | jq -r '.result.records[0].SettingValue // "false"')
+    # A missing row means "couldn't read it", NOT "license is off" — default
+    # to empty (unknown), never to "false". OrganizationSettingsDetail is not
+    # queryable (INVALID_TYPE) on some org editions (for example Developer
+    # Edition) and can return zero rows even when queryable; both are "can't
+    # tell", and collapsing them to "false" fails closed. Use select(), not
+    # `// empty`: SettingValue is a boolean and `//` drops an explicit false.
+    ECICALLSCORINGAI_ENABLED=$(echo "$ECICALLSCORINGAI_JSON" | jq -r '.result.records[0].SettingValue | select(. != null)')
   fi
 fi
 
-if [[ -z "$ECICALLSCORINGAI_ENABLED" ]]; then
-  echo "Could not determine AI call coaching license state — ECICallScoringAI query failed."
-  echo "   Verify the CLI session is valid (sf org login web --alias $ORG_ALIAS) and re-run."
+# Only an EXPLICIT negative refuses. An unknown result — the query was
+# rejected (INVALID_TYPE on this org shape) or returned no row — must NOT
+# hard-fail: doing so blocks legitimately-licensed orgs where
+# OrganizationSettingsDetail simply isn't queryable. This mirrors the Phase 0
+# ConversationPilot gate, which defers to SOAP on any non-conclusive read. The
+# 2a-pre GenAI TYPE_UNAVAILABLE gate above catches most unlicensed orgs, and
+# the updateMetadata write below is the final check — a truly unlicensed org
+# faults on the write. Closes the residual gap the earlier
+# GenAI-proxy fix left behind.
+if [[ "$ECICALLSCORINGAI_ENABLED" == "false" ]]; then
+  echo "AI call coaching is not available in this org and org requires Agentforce for Sales license."
   exit 1
 fi
 
-if [[ "$ECICALLSCORINGAI_ENABLED" != "true" ]]; then
-  echo "AI call coaching is not available in this org and org requires Agentforce for Sales license."
-  exit 1
+if [[ -z "$ECICALLSCORINGAI_ENABLED" ]]; then
+  echo "Couldn't confirm the AI Call Scoring license on this org — continuing;"
+  echo "   if the license is missing, the enable step will report it."
 fi
 
 # 2b. ECI must be enabled — this skill is ECI-only.
@@ -363,7 +376,7 @@ EOF
     # read-only and updateMetadata returns INSUFFICIENT_ACCESS_OR_READONLY.
     # This is a transient state that self-resolves in a few minutes, not a
     # permanent failure — surface a wait-and-retry message instead of the
-    # generic error. W-23968462.
+    # generic error.
     case "$CS_RESULT" in
       WRITE_ERROR:INSUFFICIENT_ACCESS_OR_READONLY*)
         echo "   Einstein Conversation Insights is still finishing turning on."
@@ -388,31 +401,40 @@ CCR_LOOKUP=$(sf api request rest \
   "services/data/v68.0/tooling/query/?q=SELECT+Id,SettingValue+FROM+OrganizationSettingsDetail+WHERE+SettingName='CallCoachingReady'+AND+DataType='OrgPermissionSettings'" \
   --target-org "$ORG_ALIAS" 2>/dev/null) || true
 
-CCR_COUNT=$(echo "$CCR_LOOKUP" | jq -r '.totalSize // 0' 2>/dev/null || echo 0)
-if [[ "$CCR_COUNT" == "0" ]]; then
-  echo "Could not locate the CallCoachingReady OrgPermission record on this org."
-  exit 1
-fi
+# On some org editions (for example Developer Edition), OrganizationSettingsDetail
+# isn't exposed at all (INVALID_TYPE) — the same unqueryable shape the Phase 3
+# license gate tolerates. The authoritative enable (enableECICallScoring, flipped
+# above and re-verified below) has already succeeded, so a CallCoachingReady
+# lookup we physically cannot run must not fail the enable closed.
+if echo "$CCR_LOOKUP" | grep -q '"errorCode"[[:space:]]*:[[:space:]]*"INVALID_TYPE"'; then
+  echo "CallCoachingReady OrgPermission isn't queryable on this org — skipping (Call Coaching is already enabled)."
+else
+  CCR_COUNT=$(echo "$CCR_LOOKUP" | jq -r '.totalSize // 0' 2>/dev/null || echo 0)
+  if [[ "$CCR_COUNT" == "0" ]]; then
+    echo "Could not locate the CallCoachingReady OrgPermission record on this org."
+    exit 1
+  fi
 
-CCR_ID=$(echo "$CCR_LOOKUP" | jq -r '.records[0].Id')
-CCR_CURRENT=$(echo "$CCR_LOOKUP" | jq -r '.records[0].SettingValue')
+  CCR_ID=$(echo "$CCR_LOOKUP" | jq -r '.records[0].Id')
+  CCR_CURRENT=$(echo "$CCR_LOOKUP" | jq -r '.records[0].SettingValue')
 
-if [[ "$CCR_CURRENT" == "true" ]]; then
-  echo "CallCoachingReady is already enabled — skipping."
-else
-  echo "Enabling CallCoachingReady..."
-  if CCR_PATCH_RESP=$(sf api request rest \
-      "services/data/v68.0/tooling/sobjects/OrganizationSettingsDetail/${CCR_ID}" \
-      --target-org "$ORG_ALIAS" \
-      --method PATCH \
-      --header 'Content-Type: application/json' \
-      --body '{"SettingValue": true}' \
-      2>/dev/null); then
-    echo "   CallCoachingReady enabled"
+  if [[ "$CCR_CURRENT" == "true" ]]; then
+    echo "CallCoachingReady is already enabled — skipping."
   else
-    echo "   Failed to enable CallCoachingReady"
-    echo "   $CCR_PATCH_RESP"
-    exit 1
+    echo "Enabling CallCoachingReady..."
+    if CCR_PATCH_RESP=$(sf api request rest \
+        "services/data/v68.0/tooling/sobjects/OrganizationSettingsDetail/${CCR_ID}" \
+        --target-org "$ORG_ALIAS" \
+        --method PATCH \
+        --header 'Content-Type: application/json' \
+        --body '{"SettingValue": true}' \
+        2>/dev/null); then
+      echo "   CallCoachingReady enabled"
+    else
+      echo "   Failed to enable CallCoachingReady"
+      echo "   $CCR_PATCH_RESP"
+      exit 1
+    fi
   fi
 fi
 

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 |
 
 ---