@salesforce/afv-skills 1.66.0 → 1.67.0

package/skills/platform-widget-generate/examples/localized-labels.json

@@ -0,0 +1,57 @@
+{
+  "type": "lightning__agentforceWidget",
+  "contentBody": {
+    "widgetBody": {
+      "definition": "tile/widget",
+      "children": [
+        {
+          "definition": "tile/column",
+          "attributes": { "gap": "md" },
+          "children": [
+            {
+              "definition": "tile/text",
+              "attributes": { "text": "{!$Label.c.OrderStatus_Heading}", "variant": "h1" }
+            },
+            {
+              "definition": "tile/row",
+              "attributes": { "gap": "sm", "align": "center" },
+              "children": [
+                {
+                  "definition": "tile/text",
+                  "attributes": { "text": "{!$Label.c.OrderStatus_OrderNumberCaption}", "variant": "caption" }
+                },
+                {
+                  "definition": "tile/text",
+                  "attributes": { "text": "{!$attrs.orderNumber}" }
+                }
+              ]
+            },
+            {
+              "definition": "tile/badge",
+              "attributes": {
+                "label": "{!IF($attrs.isShipped, $Label.c.OrderStatus_ShippedStatus, $Label.c.OrderStatus_ProcessingStatus)}",
+                "variant": "{!IF($attrs.isShipped, 'success', 'info')}"
+              }
+            },
+            {
+              "definition": "tile/text",
+              "attributes": { "text": "{!$Label.c.OrderStatus_ItemsPrefix & ' ' & TEXT($attrs.itemCount)}" }
+            },
+            {
+              "definition": "tile/button",
+              "attributes": {
+                "label": "{!$Label.c.OrderStatus_TrackButton}",
+                "variant": "primary",
+                "actions": {
+                  "click": [
+                    { "definition": "action/openLink", "attributes": { "url": "{!$attrs.trackingUrl}" } }
+                  ]
+                }
+              }
+            }
+          ]
+        }
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,29 @@
+# Widget Actions
+
+Complete `tile/button` examples for the two supported action definitions. The action table and the action-less-button rule live in SKILL.md *Actions*.
+
+---
+
+## `action/sendMessage` and `action/openLink`
+
+```json
+{
+  "definition": "tile/button",
+  "attributes": {
+    "label": "Button Label",
+    "variant": "primary",
+    "actions": { "click": [ { "definition": "action/sendMessage", "attributes": { "content": "content" } } ] }
+  }
+}
+```
+
+```json
+{
+   "definition": "tile/button",
+   "attributes": {
+      "label": "Button Label",
+      "variant": "primary",
+      "actions": { "click": [ { "definition": "action/openLink", "attributes": { "url": "https://www.example.com" } } ] }
+   }
+}
+```

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

@@ -12,3 +12,4 @@ Report each check individually as `pass` or `fail (<reason>)`.
 - **`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`.
+- **`labels-valid`** — if the user did not ask for localization, `<widgetName>.json` contains no `$Label` (report `pass (not requested)`). Otherwise every `$Label` follows the rules in `references/widget-labels.md` and appears in the step 10 report.

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-digital-engagement-channel-configure/SKILL.md

@@ -144,7 +144,7 @@ All steps are sequential. Do not skip or reorder.
 
 11. **Apply standard parameters** — if the user needs standard pre-chat fields, generate `<standardParameters>` elements with `parameterType`. If the channel uses Flow-based routing and the user specifies flow variable mappings, include `<actionParameterMappings>` with `actionParameterName` to map each parameter to a flow input variable.
 
-12. **Apply custom parameters** — if the user needs pre-chat data collection, generate `<customParameters>` elements with `name`, `masterLabel`, `parameterDataType`, `externalParameterName`, and `maxLength`. If the channel uses Flow-based routing and the user specifies flow variable mappings, include `<actionParameterMappings>` with `actionParameterName` to map each parameter to a flow input variable.
+12. **Apply custom parameters** — if the user needs pre-chat data collection, generate `<customParameters>` elements with `name`, `masterLabel`, `parameterDataType`, `externalParameterName`, and `maxLength`. Always set `parameterDataType` to `String` — the channel accepts no other value (the field's actual type, including Checkbox/Number/dropdown, is set at the deployment level via `formFieldType`, not here). If the channel uses Flow-based routing and the user specifies flow variable mappings, include `<actionParameterMappings>` with `actionParameterName` to map each parameter to a flow input variable.
 
 13. **Generate the file** — produce the `.messagingChannel-meta.xml` file following the template structure. Place at the path the user specifies, or default to the project's metadata source path under `messagingChannels/`.
 
@@ -216,7 +216,9 @@ All steps are sequential. Do not skip or reorder.
 | "Only active Agentforce Service Agents are supported" on deploy | Bot is inactive — run `sf agent activate` before deploying |
 | Flow or ASA routing fails without fallback queue | `sessionHandlerQueue` is mandatory when `sessionHandlerType` is `Flow` or `AgentforceServiceAgent` |
 | JWT verification not working | Connected app and certificate must be configured for the org |
-| Custom parameters not collected | `name` must be unique per channel; `parameterDataType` defaults to `Text` |
+| Custom parameters not collected | `name` must be unique per channel |
+| `<customParameters>` deploy fails: "bad value for restricted picklist field" | `parameterDataType` was set to something other than `String`. Channel custom parameters are always `String`; set the field's actual type (Number, Checkbox, dropdown) at the deployment level, not here |
+| Removing a custom parameter: "can't be deleted as it is referenced elsewhere" | **Check before deploying, not after.** Every deployment on this channel whose pre-chat form uses the param must first drop that field and be published (user-approved); remove the param's `actionParameterMappings` in a separate deploy first. See `references/channel_settings.md` §Removing a Custom Parameter |
 | Automated responses not showing | Use exact `type` values (`OptOutConfirmation`, `HelpResponse`); XML-escape special characters |
 | Channel deployed but messages not routing | Channel must be activated after deployment — it defaults to inactive |
 | "You can't enable Session-Based Chat for verified users" | Set `isSynchronousChatEnabled` to `false` for Auth channels — session-based chat is only valid for UnAuth |

package/skills/service-digital-engagement-channel-configure/references/channel_settings.md

@@ -196,11 +196,13 @@ Repeatable element — one block per pre-chat field for data collection.
 |-------|------|----------|-------------|
 | `name` | String | Yes | Unique API name for the parameter |
 | `masterLabel` | String | Yes | Display label shown to agent/user |
-| `parameterDataType` | Enum | Yes | `String`, `Number`, `Boolean` |
+| `parameterDataType` | String | Yes | **Always `String`** — see note below |
 | `externalParameterName` | String | Yes | External mapping name for the parameter |
-| `maxLength` | Integer | No | Max chars for Text type (default 255) |
+| `maxLength` | Integer | No | Max chars (default 255) |
 | `actionParameterMappings` | Object | No | Maps this parameter to an Omni-Channel Flow action input variable |
 
+> **`parameterDataType` is always `String`.** Every channel custom parameter deploys as `String`, regardless of the field's logical type. The metadata field's declared type is the broad `FlowDataType` enum (`Apex`, `Boolean`, `Currency`, `Date`, `DateTime`, `Multipicklist`, `Number`, `Picklist`, `SObject`, `String`, `Time`), but `MessagingChannel` restricts it at deploy time to `String` only — any other value fails with *"bad value for restricted picklist field."* The parameter's actual data type (Number, Checkbox/Boolean, dropdown, etc.) is not set on the channel; it is chosen at the **deployment** level in the pre-chat New Custom Parameter screen — i.e. via the Embedded Service form field's `formFieldType` (see `service-digital-engagement-deployment-configure`).
+
 ### Action Parameter Mappings
 
 When the channel uses Flow-based routing, `actionParameterMappings` maps a custom parameter to a flow input variable so the value collected from the user is passed into the routing flow.
@@ -222,6 +224,15 @@ When the channel uses Flow-based routing, `actionParameterMappings` maps a custo
 </customParameters>
 ```
 
+### Removing a Custom Parameter
+
+A parameter still used by a pre-chat form can't be deleted ("can't be deleted as it is referenced elsewhere"). Several deployments can share one channel, so **check every deployment before writing**: retrieve all `EmbeddedServiceConfig` and find each one whose `<messagingChannel>` is this channel and whose form has `<formField>` = the param `name`. Don't use a failed channel deploy to find them.
+
+1. If another deployment the user didn't mention still uses the param, stop and ask; changing it is outside the request.
+2. Each referencing deployment: remove the field (via `service-digital-engagement-deployment-configure`) and publish it after the user approves.
+3. If the param has `actionParameterMappings`, deploy the channel with the mapping removed first.
+4. Deploy the channel without that parameter's `<customParameters>` block; keep every other parameter.
+
 ---
 
 ## Automated Responses (`<automatedResponses>`)