@salesforce/afv-skills 1.46.0 → 1.48.0

package/skills/service-omni-supervisor-users-create/scripts/run-create.sh

@@ -0,0 +1,296 @@
+#!/usr/bin/env bash
+# run-create.sh - INTERNAL (invoke via detect-and-create.sh, which enforces the safe_to_write guard): render Apex tokens, execute, parse created users, set passwords via separate System.setPassword; on password failure the user stays active + reset_required (never deactivated). Contract + security: SKILL.md + references/apex-template-notes.md.
+
+set -euo pipefail
+
+if [ $# -lt 4 ]; then
+  echo '{"error":"Usage: bash run-create.sh <org-alias> <count> <profile-id> <org-suffix>"}' >&2
+  exit 1
+fi
+
+ORG="$1"
+COUNT="$2"
+PROFILE_ID="$3"
+SUFFIX="$4"
+
+# Validate every arg BEFORE it is sed-substituted into anonymous Apex. These tokens are interpolated
+# into executable Apex, so anything outside a strict grammar (Apex/sed metacharacters, code) is
+# rejected up front rather than executed.
+if ! [[ "$COUNT" =~ ^[1-9][0-9]{0,2}$ ]]; then
+  echo "{\"error\":\"Invalid count '$COUNT' (expected a positive integer 1-999).\"}" >&2; exit 1
+fi
+if ! [[ "$PROFILE_ID" =~ ^[A-Za-z0-9]{15}([A-Za-z0-9]{3})?$ ]]; then
+  echo "{\"error\":\"Invalid profile-id '$PROFILE_ID' (expected a 15- or 18-char Salesforce Id).\"}" >&2; exit 1
+fi
+if ! [[ "$SUFFIX" =~ ^[A-Za-z0-9]{1,18}$ ]]; then
+  echo "{\"error\":\"Invalid org-suffix '$SUFFIX' (expected 1-18 alphanumeric chars).\"}" >&2; exit 1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+TEMPLATE="$SCRIPT_DIR/../assets/create-supervisors.apex.template"
+
+if [ ! -f "$TEMPLATE" ]; then
+  echo "{\"error\":\"Apex template not found: $TEMPLATE\"}" >&2
+  exit 1
+fi
+
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+RESOLVED="$WORK/create-supervisors.resolved.apex"
+
+sed -e "s|__COUNT__|${COUNT}|g" \
+    -e "s|__PROFILE_ID__|${PROFILE_ID}|g" \
+    -e "s|__SUFFIX__|${SUFFIX}|g" \
+    "$TEMPLATE" > "$RESOLVED"
+
+APEX_JSON=$(sf apex run --target-org "$ORG" --file "$RESOLVED" --json 2>/dev/null || true)
+
+# Strip C0 control chars: sf embeds an unescaped debug log in .result.logs, which jq>=1.7 rejects.
+# This merges the log to one line; the grep below is anchored to tolerate that.
+APEX_JSON=$(printf '%s' "$APEX_JSON" | tr -d '\000-\037')
+
+CLI_STATUS=$(echo "$APEX_JSON" | jq -r '.status // 0' 2>/dev/null || echo "0")
+COMPILE_SUCCESS=$(echo "$APEX_JSON" | jq -r '.result.compiled // false' 2>/dev/null || echo "false")
+EXEC_SUCCESS=$(echo "$APEX_JSON"    | jq -r '.result.success  // false' 2>/dev/null || echo "false")
+
+translate_error() {
+  local raw="$1"
+  case "$raw" in
+    *LICENSE_LIMIT_EXCEEDED*)
+      echo "Org has reached its user license limit. Free up a license slot (deactivate unused users in Setup > Users) or request a larger CDO from OrgFarm."
+      ;;
+    *DUPLICATE_USERNAME*)
+      echo "Username collision with another Salesforce org (globally unique constraint). Rare - retry the skill; if it persists, another agent may be concurrently running against the same suffix."
+      ;;
+    *INVALID_EMAIL_ADDRESS*)
+      echo "Salesforce rejected the @example.com email. This should never happen - likely a bug in the skill's Apex template. Escalate."
+      ;;
+    *INSUFFICIENT_ACCESS*|*NoAccessException*)
+      echo "Executing user lacks required permission. Ensure the sf-CLI-authenticated user has System Administrator profile or equivalent."
+      ;;
+    *INVALID_LOGIN*|*INVALID_SESSION_ID*)
+      echo "Salesforce session expired. Re-authenticate: sf org login web -a $ORG -r <my-domain-url>"
+      ;;
+    *)
+      echo "$raw"
+      ;;
+  esac
+}
+
+if [ "$CLI_STATUS" != "0" ]; then
+  CLI_ERR=$(echo "$APEX_JSON" | jq -r '.message // "Unknown CLI error"' 2>/dev/null)
+  FRIENDLY=$(translate_error "$CLI_ERR")
+  echo "{\"error\":\"$FRIENDLY\",\"raw\":$(echo "$CLI_ERR" | jq -R .)}" >&2
+  exit 1
+fi
+
+if [ "$COMPILE_SUCCESS" != "true" ]; then
+  COMPILE_ERR=$(echo "$APEX_JSON" | jq -r '.result.compileProblem // "Unknown compile error"' 2>/dev/null)
+  COMPILE_LINE=$(echo "$APEX_JSON" | jq -r '.result.line // "?"' 2>/dev/null)
+  echo "{\"error\":\"Apex compile failed at line $COMPILE_LINE: $COMPILE_ERR\"}" >&2
+  exit 1
+fi
+
+if [ "$EXEC_SUCCESS" != "true" ]; then
+  EXEC_ERR=$(echo "$APEX_JSON" | jq -r '.result.exceptionMessage // "Unknown execution error"' 2>/dev/null)
+  if [ -z "$EXEC_ERR" ] || [ "$EXEC_ERR" = "Unknown execution error" ] || [ "$EXEC_ERR" = "null" ]; then
+    EXEC_ERR=$(echo "$APEX_JSON" | jq -r '.message // "Unknown execution error"' 2>/dev/null)
+  fi
+  FRIENDLY=$(translate_error "$EXEC_ERR")
+  echo "{\"error\":\"$FRIENDLY\",\"raw\":$(echo "$EXEC_ERR" | jq -R .)}" >&2
+  exit 1
+fi
+
+# Parse SUPERVISOR_CREATED|<userId>|<username>|<email> from the log; decode the HTML-encoded pipe
+# (&#124;) that sf emits, else the grep misses every user.
+LOG=$(echo "$APEX_JSON" | jq -r '.result.logs // ""' 2>/dev/null | sed 's/&#124;/|/g')
+
+# Anchor on a real 005 Id + @example.com domain so the match ignores the Apex source echoed in the merged log.
+CREATED_RAW=$(echo "$LOG" | grep -oE 'SUPERVISOR_CREATED\|005[a-zA-Z0-9]{15}\|[^|]+@example\.com\|[^|]+@example\.com' || true)
+
+if [ -z "$CREATED_RAW" ]; then
+  CREATED_USERS_JSON='[]'
+else
+  CREATED_USERS_JSON=$(echo "$CREATED_RAW" \
+    | awk -F'|' '
+        BEGIN { print "[" }
+        NR > 1 { printf "," }
+        {
+          printf "{\"id\":\"%s\",\"username\":\"%s\",\"email\":\"%s\"}", $2, $3, $4
+        }
+        END { print "]" }
+    ')
+  if ! echo "$CREATED_USERS_JSON" | jq -c '.' >/dev/null 2>&1; then
+    echo "{\"error\":\"Internal parse error: SUPERVISOR_CREATED lines produced invalid JSON. Users may have been created but this script cannot capture them.\",\"raw_lines\":$(echo "$CREATED_RAW" | jq -Rs .)}" >&2
+    exit 1
+  fi
+  CREATED_USERS_JSON=$(echo "$CREATED_USERS_JSON" | jq -c '.')
+fi
+
+# Set each User's password via System.setPassword (the only working path for Apex-inserted users).
+# Fail-closed on the TraceFlag gate below; on failure the User stays active + reset_required.
+# Full security rationale: references/apex-template-notes.md.
+ENRICHED_USERS='[]'
+NEEDS_RESET='[]'
+ROLLED_BACK='[]'
+
+# Generated passwords are written to a restricted (0600) file and NEVER returned in stdout, so
+# plaintext cannot enter an AI/tool transcript when this leaf is invoked directly. The coordinator
+# passes OMNI_CREDENTIALS_FILE/OMNI_CREDENTIALS_KEY to escrow into its own file; standalone runs
+# default to ./CREDENTIALS.json. File format: { "<key>": [ {username, password}, ... ] }.
+# Secrets never touch argv/env (both visible via process inspection): each {username,password} pair is
+# appended as one JSON line to this 0600 temp file (inside $WORK, mode 0700) and fed to jq only via
+# stdin / --slurpfile. $WORK is removed by the EXIT trap, so the plaintext file never persists.
+CRED_PAIRS_FILE="$WORK/cred-pairs.jsonl"
+: > "$CRED_PAIRS_FILE"; chmod 600 "$CRED_PAIRS_FILE" 2>/dev/null || true
+CRED_COUNT=0
+CRED_FILE="${OMNI_CREDENTIALS_FILE:-$PWD/CREDENTIALS.json}"
+CRED_KEY="${OMNI_CREDENTIALS_KEY:-service-omni-supervisor-users-create}"
+CRED_WRITTEN="false"
+write_credentials() {
+  # $1 = path to a JSONL file of {username,password} objects. Secret-bearing pairs are read via
+  # --slurpfile (a file, never argv); the existing credentials file is piped in via stdin.
+  local pairs_file="$1" existing='{}' tmp
+  [ -f "$CRED_FILE" ] && existing=$(cat "$CRED_FILE" 2>/dev/null || echo '{}')
+  tmp=$(mktemp) || return 1
+  if ! printf '%s' "$existing" | jq --arg k "$CRED_KEY" --slurpfile c "$pairs_file" '. + {($k): $c}' > "$tmp" 2>/dev/null || [ ! -s "$tmp" ]; then
+    rm -f "$tmp"; return 1
+  fi
+  if ! mv "$tmp" "$CRED_FILE" 2>/dev/null; then rm -f "$tmp"; return 1; fi
+  chmod 600 "$CRED_FILE" 2>/dev/null || true
+  return 0
+}
+
+set_password_via_apex() {
+  # $1=user_id  $2=plaintext_password. Echoes "ok" on success, else the exception text.
+  local uid="$1" pw="$2" apex_file res
+  apex_file="$WORK/setpw.apex"
+  # uid (18-char Id) and pw ([A-Za-z0-9]) can't break out of the Apex string literal.
+  printf "System.setPassword('%s', '%s');\n" "$uid" "$pw" > "$apex_file"
+  res=$(sf apex run --target-org "$ORG" --file "$apex_file" --json 2>/dev/null | tr -d '\000-\037' || true)
+  rm -f "$apex_file"
+  if [ "$(echo "$res" | jq -r '.result.success // false' 2>/dev/null)" = "true" ]; then
+    echo "ok"
+  else
+    echo "$res" | jq -r '.result.exceptionMessage // .message // "setPassword failed"' 2>/dev/null
+  fi
+}
+
+# TraceFlag gate (fail-closed): prove no active TraceFlag exists for the running user BEFORE any
+# System.setPassword, else a password literal could persist to a queryable ApexLog. Cannot prove safe
+# => no password set, users left active + reset_required. See references/apex-template-notes.md.
+TRACEFLAG_SAFE=false
+TRACEFLAG_REASON="TraceFlag state could not be determined"
+ME_UNAME=$(sf org display --target-org "$ORG" --json 2>/dev/null | jq -r '.result.username // empty' 2>/dev/null || true)
+if [ -z "${ME_UNAME:-}" ]; then
+  TRACEFLAG_REASON="could not resolve the running user (sf org display failed)"
+else
+  ME_UID=$(sf data query --target-org "$ORG" \
+    --query "SELECT Id FROM User WHERE Username='$ME_UNAME' LIMIT 1" \
+    --json 2>/dev/null | jq -r '.result.records[0].Id // empty' 2>/dev/null || true)
+  if [ -z "${ME_UID:-}" ]; then
+    TRACEFLAG_REASON="could not resolve the running user's Id"
+  else
+    NOW_UTC=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+    if TF_JSON=$(sf data query --target-org "$ORG" --use-tooling-api \
+        --query "SELECT Id FROM TraceFlag WHERE TracedEntityId='$ME_UID' AND ExpirationDate > $NOW_UTC" \
+        --json 2>/dev/null) && [ -n "$TF_JSON" ]; then
+      TF_STATUS=$(echo "$TF_JSON" | jq -r '.status // 1' 2>/dev/null || echo 1)
+      if [ "$TF_STATUS" = "0" ]; then
+        TF_COUNT=$(echo "$TF_JSON" | jq -r 'if (.result.totalSize != null) then .result.totalSize elif (.result.records != null) then (.result.records | length) else "unknown" end' 2>/dev/null || echo "unknown")
+        if [ "$TF_COUNT" = "0" ]; then
+          TRACEFLAG_SAFE=true
+          TRACEFLAG_REASON=""
+        elif [ "$TF_COUNT" = "unknown" ]; then
+          TRACEFLAG_REASON="the TraceFlag query returned an unparseable result"
+        else
+          TRACEFLAG_REASON="an active Apex debug TraceFlag exists for the running user ($TF_COUNT found)"
+        fi
+      else
+        TRACEFLAG_REASON="the TraceFlag Tooling API query returned an error status"
+      fi
+    else
+      TRACEFLAG_REASON="the TraceFlag Tooling API query failed"
+    fi
+  fi
+fi
+
+if [ "$(echo "$CREATED_USERS_JSON" | jq -r 'length')" -gt 0 ]; then
+  while IFS= read -r row; do
+    USER_ID=$(echo "$row" | jq -r '.id')
+    UNAME=$(echo "$row" | jq -r '.username')
+    EMAIL=$(echo "$row" | jq -r '.email')
+
+    if [ "$TRACEFLAG_SAFE" != "true" ]; then
+      # Fail closed: skip setPassword, keep the User active + flag for manual reset.
+      NEEDS_RESET=$(echo "$NEEDS_RESET" | jq -c --arg u "$UNAME" '. + [$u]')
+      ENRICHED_USERS=$(echo "$ENRICHED_USERS" | jq -c \
+        --arg id "$USER_ID" --arg u "$UNAME" --arg e "$EMAIL" \
+        '. + [{id: $id, username: $u, email: $e, password: null, password_status: "reset_required", password_error: "skipped: TraceFlag safety could not be proven (fail-closed)"}]')
+      continue
+    fi
+
+    # Strong [A-Za-z0-9] password + fixed mixed-class suffix (Salesforce complexity). The || true
+    # swallows tr's SIGPIPE (head closes the pipe) so pipefail+set -e don't abort mid-insert.
+    RAND="$(LC_ALL=C tr -dc 'A-Za-z0-9' < /dev/urandom 2>/dev/null | head -c 14 || true)"
+    PW="${RAND}aB3"
+    SETPW_RESULT=$(set_password_via_apex "$USER_ID" "$PW")
+
+    if [ "$SETPW_RESULT" = "ok" ]; then
+      # Feed the SECRET via stdin (never argv/env); username is not secret so --arg is fine.
+      printf '%s' "$PW" | jq -Rsc --arg u "$UNAME" '{username: $u, password: .}' >> "$CRED_PAIRS_FILE"
+      CRED_COUNT=$((CRED_COUNT + 1))
+      ENRICHED_USERS=$(echo "$ENRICHED_USERS" | jq -c \
+        --arg id "$USER_ID" --arg u "$UNAME" --arg e "$EMAIL" \
+        '. + [{id: $id, username: $u, email: $e, password: null, password_status: "generated"}]')
+    else
+      # Non-destructive: keep the active User, flag it for a manual password reset.
+      NEEDS_RESET=$(echo "$NEEDS_RESET" | jq -c --arg u "$UNAME" '. + [$u]')
+      ENRICHED_USERS=$(echo "$ENRICHED_USERS" | jq -c \
+        --arg id "$USER_ID" --arg u "$UNAME" --arg e "$EMAIL" --arg r "$SETPW_RESULT" \
+        '. + [{id: $id, username: $u, email: $e, password: null, password_status: "reset_required", password_error: $r}]')
+    fi
+  done < <(echo "$CREATED_USERS_JSON" | jq -c '.[]')
+fi
+
+# Escrow generated passwords to the restricted file; never emit plaintext in stdout. Fail-closed:
+# if escrow fails, the passwords were set on-org but cannot be handed back, so flag those users for a
+# manual reset rather than leaking the plaintext.
+CRED_WARNING=""
+if [ "$CRED_COUNT" -gt 0 ]; then
+  if write_credentials "$CRED_PAIRS_FILE"; then
+    CRED_WRITTEN="true"
+  else
+    CRED_WARNING="Passwords were set on the created users but could NOT be escrowed to the credentials file ($CRED_FILE); plaintext was deliberately NOT emitted to stdout. Reset these users' passwords in Setup > Users."
+    # Escrow failed → the plaintext is unrecoverable, so these users genuinely need a manual reset:
+    # add them to users_needing_password_reset (not just the per-user status) before flipping status.
+    ESCROW_FAILED_UNAMES=$(echo "$ENRICHED_USERS" | jq -c '[ .[] | select(.password_status=="generated") | .username ]')
+    NEEDS_RESET=$(jq -c -n --argjson a "$NEEDS_RESET" --argjson b "$ESCROW_FAILED_UNAMES" '$a + $b | unique')
+    ENRICHED_USERS=$(echo "$ENRICHED_USERS" | jq -c '[ .[] | if .password_status=="generated" then (.password_status="reset_required" | .password_error="escrow_failed") else . end ]')
+  fi
+fi
+
+# Surface why password generation was skipped when the TraceFlag gate failed.
+SECURITY_WARNING=""
+if [ "$TRACEFLAG_SAFE" != "true" ]; then
+  SECURITY_WARNING="Password generation was SKIPPED (fail-closed) because ${TRACEFLAG_REASON}. No System.setPassword was executed, so no plaintext could enter an ApexLog. The created users are ACTIVE and flagged password_status:\"reset_required\" - set their passwords in Setup > Users after confirming no debug TraceFlag is active, or disable the TraceFlag and re-run."
+fi
+[ -n "$CRED_WARNING" ] && SECURITY_WARNING="${SECURITY_WARNING:+$SECURITY_WARNING }$CRED_WARNING"
+
+jq -n \
+  --argjson created "$ENRICHED_USERS" \
+  --argjson needs_reset "$NEEDS_RESET" \
+  --argjson rolled_back "$ROLLED_BACK" \
+  --arg security_warning "$SECURITY_WARNING" \
+  --arg cred_written "$CRED_WRITTEN" \
+  --arg cred_file "$CRED_FILE" \
+  '{
+    created_users: $created,
+    created_count: ($created | length),
+    users_needing_password_reset: $needs_reset,
+    rolled_back_users: $rolled_back,
+    credentials_written: ($cred_written == "true"),
+    credentials_file: (if $cred_written == "true" then $cred_file else null end),
+    security_warning: (if $security_warning == "" then null else $security_warning end),
+    security_note: "Passwords are set via anonymous Apex System.setPassword. The plaintext appears in the inline executeAnonymous debug log and, ONLY when a debug-log TraceFlag is active for the running user, in a queryable ApexLog row. To avoid ever persisting plaintext to a log, this script FAILS CLOSED BEFORE the first System.setPassword: it proves via a SOQL-filtered Tooling API query (ExpirationDate > now) that no active TraceFlag exists for the running user. If safety cannot be positively proven - the running user cannot be resolved, the Tooling API query fails or is unparseable, or any active TraceFlag exists - NO password is generated at all; the created users are left ACTIVE and flagged password_status:\"reset_required\", and security_warning explains why. Generated passwords are NEVER returned in this output; they are written to a restricted 0600 credentials_file (default ./CREDENTIALS.json, or OMNI_CREDENTIALS_FILE) so plaintext cannot enter a tool/AI transcript. Read the file once, distribute securely, then delete it. Set passwords for reset_required users in Setup > Users after ensuring no debug TraceFlag is active (or disable the TraceFlag and re-run)."
+  }'

package/skills/service-omni-work-skill-routing-configure/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: service-omni-work-skill-routing-configure
+description: "Use to author an Omni WorkSkillRouting rule (field-based skill criteria): map a related-entity field value to a required Omni Skill (e.g. add the Voice skill when Case.Origin = Phone), deployed as one WorkSkillRouting record via the Metadata API. Idempotent via the Metadata API files[].state signal; one rule per related entity. Triggers: add field-based skill routing, route by a Case field to a skill, route by a MessagingSession field to a skill, configure attribute-based skills routing, require an Omni skill for a field value. Do not use to create the Skill or bind agents to it (service-omni-skills-based-routing-configure), to create agent users, or to configure queues."
+allowed-tools: Bash Read Write Edit Glob Grep
+metadata:
+  version: "1.0"
+  domains: ["Service"]
+  minApiVersion: "66.0"
+  relatedSkills:
+    - "service-omni-base-settings-configure"
+    - "service-omni-channel-setup-coordinate"
+    - "service-omni-skills-based-routing-configure"
+  accessCheck:
+    - type: license
+      value: ServiceCloud
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6"
+    - tool: ["python3"]
+      semver: ">=3.8"
+    - tool: ["sf"]
+      semver: ">=2.139.6"
+---
+
+# service-omni-work-skill-routing-configure
+
+Author an Omni **WorkSkillRouting** rule so work is routed to agents by a **field value on the work record**, not just by skills the agent happens to hold. Where `service-omni-skills-based-routing-configure` makes an agent *routable* (Skill + ServiceResource + ServiceResourceSkill), this skill decides *which skill a work item requires* based on one of its fields — for example "when `Case.Origin` = `Phone`, require the `Voice` skill". The rule is one `WorkSkillRouting` record (a header plus one `workSkillRoutingAttributes` mapping) deployed via the Metadata API. It runs after the referenced Skill exists and belongs to the same routing family coordinated by `service-omni-channel-setup-coordinate`.
+
+## Inputs
+
+```bash
+bash scripts/configure-and-report.sh <org-alias> <related_entity> <field> <skill> <value> [rule_master_label]
+```
+
+- `org-alias` (required).
+- `related_entity` (required). The sObject the rule applies to (e.g. `Case`, `MessagingSession`, `LiveChatTranscript`, `Lead`, `VoiceCall`).
+- `field` (required). The field the attribute evaluates (e.g. `Case.Origin` or `Origin`). Bare standard fields are qualified with the related entity before deploy, so `Origin` becomes `Case.Origin` instead of being misread as a custom-field metadata name.
+- `skill` (required). The Omni `Skill` DeveloperName required when the field matches (e.g. `Voice`).
+- `value` (required). The field value that maps to the skill (e.g. `Phone`). Plain values only; XML-reserved characters are not supported.
+- `rule_master_label` (optional). MasterLabel for the rule; defaults to `<related_entity> Skill Routing`.
+
+Env overrides: `RULE_DEVELOPER_NAME` (fullName of the rule, default the related-entity name — one rule per entity), `IS_ACTIVE` (default `true`), `SKILL_LEVEL` (0–10), `SKILL_PRIORITY` (0–10, additional-skill drop order), `IS_ADDITIONAL_SKILL` (`true`/`false`).
+
+## Preconditions and safety
+
+- Target org authenticated via `sf` CLI, Service Cloud license, `sf` CLI ≥ 2.139.6.
+- Omni-Channel base settings enabled with **skills-based routing** turned on (`service-omni-base-settings-configure`).
+- The referenced `Skill` already exists (`service-omni-skills-based-routing-configure`).
+- The three-way `safe_to_write` production guard applies.
+
+## Run
+
+1. **safe_to_write** — query `Organization`; refuse to write to a real production org.
+2. **Skill prereq** — query `Skill` by DeveloperName; if absent, block and point at `service-omni-skills-based-routing-configure`.
+3. **Merge** — read the existing `WorkSkillRouting.Metadata` through the Tooling API, preserve unrelated attributes, and replace or append only the requested `(field, value)` mapping. An inconclusive read blocks the write; `WSR_REPLACE=1` is the explicit destructive-replacement escape hatch.
+4. **Deploy** — materialize the merged `WorkSkillRouting` record (elements in XSD/alphabetical order) and deploy it via the Metadata API (async + poll to a terminal state).
+5. **Classify** — read `files[].state` (`Created` / `Changed` / `Unchanged`) to report `created` / `updated` / `reused`.
+
+## Behavior
+
+**Idempotent + merge-safe.** WorkSkillRouting permits a single rule per related entity, so the rule's fullName defaults to the entity name. Re-running the same mapping reports `reused`; a new mapping is merged into the existing attribute list; changing the same field/value mapping updates only that entry. The skill never silently replaces an existing rule when its current metadata could not be read.
+
+**Graceful degradation.** WorkSkillRouting is not provisioned on every org (some trials/CDOs). A deploy failure shaped like `INVALID_TYPE` / "not available" / "WorkSkillRouting" is reported as `blocked` with a clear limitation message and a pointer to base settings — the skill surfaces the limitation rather than crashing.
+
+## Output contract
+
+A single JSON object: `status` ∈ `created` | `updated` | `reused` | `blocked` (plus `action_needed` in plan mode), `rule` (`{developer_name, master_label, related_entity, is_active, state}`), `attribute` (`{field, skill, value, skill_level, skill_priority, is_additional_skill}`), `merge` (`{merged_from_existing, attribute_count, preserved_count}`), `deploy_id`, `manual_actions`, `blocking_issue`.
+
+## Limitations
+
+- One field→skill mapping per invocation and one rule per related entity. Multiple invocations safely accumulate attributes on that rule.
+- Does not create the Skill, ServiceResources, agent users, queues, or presence configuration.
+- Field/value correctness is validated by the platform at deploy time; an invalid field or value surfaces as a `blocked` deploy failure.
+
+## References
+
+| File | When to read |
+|---|---|
+| `references/api-notes.md` | WorkSkillRouting metadata shape, XSD element order, one-rule-per-entity constraint, attribute fields, and graceful-degradation triggers |
+| `scripts/tests/test_work_skill_routing_contracts.py` | When validating changes — run `python3 scripts/tests/test_work_skill_routing_contracts.py` from this skill directory |

package/skills/service-omni-work-skill-routing-configure/references/api-notes.md

@@ -0,0 +1,67 @@
+# WorkSkillRouting - API notes
+
+## Metadata type
+
+`WorkSkillRouting` is a Metadata API type (also queryable via the Tooling API). It stores a set
+of `WorkSkillRoutingAttribute` mappings that route a work item to an agent who holds the required
+skills. It extends `Metadata` and inherits `fullName`.
+
+Source path convention used by this skill:
+
+```text
+force-app/main/default/workSkillRoutings/<fullName>.workSkillRouting-meta.xml
+```
+
+## Record shape (XSD / alphabetical element order)
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<WorkSkillRouting xmlns="http://soap.sforce.com/2006/04/metadata">
+    <isActive>true</isActive>
+    <masterLabel>Case Skill Routing</masterLabel>
+    <relatedEntity>Case</relatedEntity>
+    <workSkillRoutingAttributes>
+        <field>Case.Origin</field>
+        <skill>Voice</skill>
+        <value>Phone</value>
+    </workSkillRoutingAttributes>
+</WorkSkillRouting>
+```
+
+Header fields:
+
+| Field | Type | Notes |
+|---|---|---|
+| `isActive` | boolean | Required. Whether the rule is evaluated. |
+| `masterLabel` | string | Required. Internal (untranslated) label. |
+| `relatedEntity` | string | Required. The sObject the attributes apply to. |
+| `workSkillRoutingAttributes` | array | One or more field-value -> skill mappings. |
+
+Attribute fields (emitted alphabetically: `field`, `isAdditionalSkill`, `skill`, `skillLevel`,
+`skillPriority`, `value`):
+
+| Field | Type | Notes |
+|---|---|---|
+| `field` | string | Required. Field the attribute evaluates. |
+| `isAdditionalSkill` | boolean | Additional skills are dropped after the routing-config timeout so a best-match agent can still take the work. |
+| `skill` | string | Required. Skill DeveloperName required when the field matches `value`. |
+| `skillLevel` | int | 0–10. |
+| `skillPriority` | int | 0–10. Drop order for additional skills (9–10 dropped first, 0–1 last). API 49.0+. |
+| `value` | string | Required. Field value mapped to the skill. |
+
+## One rule per entity
+
+Only one `WorkSkillRouting` rule is permitted per `relatedEntity`. This skill therefore defaults the
+rule fullName to the related-entity name (overridable via `RULE_DEVELOPER_NAME`), so re-runs converge
+on the same record instead of creating duplicates. Idempotency is read from the Metadata API
+`files[].state`: `Created` -> `created`, `Changed` -> `updated`, `Unchanged` -> `reused`.
+
+## Prerequisites and graceful degradation
+
+- The referenced `Skill` must exist first (`service-omni-skills-based-routing-configure`); the skill
+  queries `Skill` by DeveloperName and blocks with that pointer when it is missing.
+- Skills-based routing must be enabled in Omni-Channel settings
+  (`service-omni-base-settings-configure`).
+- WorkSkillRouting is not provisioned on every org (some trials/CDOs). Deploy failures shaped like
+  `INVALID_TYPE`, "not available", or naming `WorkSkillRouting` are reported as `blocked` with a
+  limitation message rather than crashing, so a coordinator can continue.