@salesforce/afv-skills 1.46.0 → 1.48.0

package/skills/service-omni-supervisor-permset-assign/scripts/verify-and-assign.sh

@@ -0,0 +1,316 @@
+#!/usr/bin/env bash
+# verify-and-assign.sh - assign PermissionSets to N supervisor users via PermissionSetAssignment POSTs; idempotent (SOQL detects existing pairs), non-destructive. Args, output contract, exit codes: SKILL.md.
+
+set -euo pipefail
+
+if [ $# -lt 1 ]; then
+  echo '{"error":"Usage: bash verify-and-assign.sh <org-alias> [<count>] [<permission-set-names-csv>]"}' >&2
+  exit 1
+fi
+
+ORG="$1"
+COUNT="${2:-1}"
+# Default to the standard ContactCenterSupervisor permset (its license-gated perms can't be
+# re-declared in a custom permset), so this skill only assigns permsets already on the org.
+PS_NAMES_CSV="${3:-ContactCenterSupervisor}"
+API_VERSION="v66.0"
+
+if ! [[ "$COUNT" =~ ^[0-9]+$ ]] || [ "$COUNT" -lt 1 ] || [ "$COUNT" -gt 5 ]; then
+  echo "{\"error\":\"Invalid count '$COUNT' - must be integer 1..5\"}" >&2
+  exit 1
+fi
+
+if ! sf org display --target-org "$ORG" --json >/dev/null 2>&1; then
+  echo "{\"error\":\"Org alias '$ORG' is not authenticated.\"}" >&2
+  exit 1
+fi
+
+PS_NAMES_JSON=$(echo "$PS_NAMES_CSV" | jq -R -c 'split(",") | map(gsub("^\\s+|\\s+$"; ""))')
+PS_COUNT=$(echo "$PS_NAMES_JSON" | jq 'length')
+
+# Each PermissionSet Name is interpolated into SOQL, so validate its DeveloperName shape before any
+# sf call; an empty CSV is also rejected.
+if [ "$PS_COUNT" -lt 1 ]; then
+  echo "{\"error\":\"No permission-set names supplied.\"}" >&2
+  exit 1
+fi
+while IFS= read -r ps_name; do
+  if ! [[ "$ps_name" =~ ^[A-Za-z][A-Za-z0-9_]{0,79}$ ]]; then
+    echo "{\"error\":\"Invalid permission-set name '$ps_name'. Each must start with a letter and contain only letters, digits, and underscores (max 80 chars).\"}" >&2
+    exit 1
+  fi
+done < <(echo "$PS_NAMES_JSON" | jq -r '.[]')
+
+emit_blocked() {
+  local msg="$1"
+  local click_path="${2:-}"
+  local suffix="${3:-}"
+
+  local manual_actions='[]'
+  if [ -n "$click_path" ]; then
+    manual_actions=$(jq -n --arg cp "$click_path" '[{id: "MANUAL_FIX", title: "Manual fix required", click_path: $cp}]')
+  fi
+
+  jq -n \
+    --arg msg "$msg" \
+    --arg suf "$suffix" \
+    --argjson count "$COUNT" \
+    --argjson ps_count "$PS_COUNT" \
+    --argjson ma "$manual_actions" \
+    '{
+      skill: "service-omni-supervisor-permset-assign",
+      status: "blocked",
+      permission_sets: [],
+      org_suffix: (if $suf == "" then null else $suf end),
+      requested_count: $count,
+      expected_assignment_count: ($count * $ps_count),
+      before: null,
+      assigned_this_run: [],
+      assigned_count: 0,
+      reused_count: 0,
+      after: null,
+      manual_actions: $ma,
+      blocking_issue: $msg
+    }'
+  exit 1
+}
+
+# emit read-only plan preview JSON and exit 0 (PLAN_ONLY mode)
+emit_plan() {
+  local status="$1"
+  local detail="$2"
+  jq -n \
+    --arg status "$status" \
+    --arg detail "$detail" \
+    '{
+      skill: "service-omni-supervisor-permset-assign",
+      status: $status,
+      plan_mode: true,
+      plan_detail: $detail,
+      manual_actions: [],
+      blocking_issue: null
+    }'
+  exit 0
+}
+
+ORG_JSON=$(sf data query --target-org "$ORG" \
+  --query "SELECT Id, IsSandbox, TrialExpirationDate, OrganizationType FROM Organization LIMIT 1" \
+  --json 2>/dev/null)
+
+ORG_ID=$(echo "$ORG_JSON"     | jq -r '.result.records[0].Id')
+IS_SANDBOX=$(echo "$ORG_JSON"  | jq -r '.result.records[0].IsSandbox')
+TRIAL_EXP=$(echo "$ORG_JSON"   | jq -r '.result.records[0].TrialExpirationDate // "null"')
+ORG_TYPE=$(echo "$ORG_JSON"    | jq -r '.result.records[0].OrganizationType')
+
+SAFE_TO_WRITE=false
+if [ "$IS_SANDBOX" = "true" ] \
+   || [ "$TRIAL_EXP" != "null" ] \
+   || [ "$ORG_TYPE" = "Developer Edition" ] \
+   || [ "$ORG_TYPE" = "Base Edition" ]; then
+  SAFE_TO_WRITE=true
+fi
+
+SUFFIX=$(echo "$ORG_ID" | tr '[:upper:]' '[:lower:]' | tail -c 9 | head -c 8)
+
+if [ "$SAFE_TO_WRITE" != "true" ]; then
+  emit_blocked "Refusing to assign permission sets on a real production customer org (IsSandbox=$IS_SANDBOX, TrialExpirationDate=$TRIAL_EXP, OrganizationType=$ORG_TYPE). Target a sandbox, trial CDO, or Developer Edition org." "" "$SUFFIX"
+fi
+
+PS_IN_CLAUSE=""
+for name in $(echo "$PS_NAMES_JSON" | jq -r '.[]'); do
+  if [ -n "$PS_IN_CLAUSE" ]; then PS_IN_CLAUSE="$PS_IN_CLAUSE,"; fi
+  PS_IN_CLAUSE="$PS_IN_CLAUSE'$name'"
+done
+
+PS_JSON=$(sf data query --target-org "$ORG" \
+  --query "SELECT Id, Name, Label FROM PermissionSet WHERE Name IN ($PS_IN_CLAUSE)" \
+  --json 2>/dev/null)
+
+FOUND_PS_COUNT=$(echo "$PS_JSON" | jq -r '.result.totalSize // 0')
+
+# A missing permset can't be self-healed: ContactCenterSupervisor is provisioned by the Service Cloud
+# license and can't be deployed; if absent, the org lacks the license/feature. Report and stop.
+if [ "$FOUND_PS_COUNT" -lt "$PS_COUNT" ]; then
+  FOUND_NAMES=$(echo "$PS_JSON" | jq -c '[.result.records[].Name]')
+  MISSING_NAMES=$(jq -n --argjson expected "$PS_NAMES_JSON" --argjson found "$FOUND_NAMES" \
+    '$expected - $found')
+  if [ "${PLAN_ONLY:-}" = "1" ]; then
+    emit_plan "action_needed" "PermissionSet(s) $MISSING_NAMES not present on the org. A --run cannot create a Salesforce-standard permset; it requires the Service Cloud license/feature. --plan makes no writes."
+  fi
+  emit_blocked \
+    "Expected PermissionSets $PS_NAMES_JSON; found $FOUND_NAMES. Missing: $MISSING_NAMES. ContactCenterSupervisor is a Salesforce-standard permission set provisioned with the Service Cloud license - it cannot be created by a deploy. Confirm the org has the contact-center supervisor entitlement." \
+    "Setup → Permission Sets - confirm 'Contact Center Supervisor' exists. If it is absent, the org lacks the required license/feature; contact Salesforce to enable it." \
+    "$SUFFIX"
+fi
+
+PERMISSION_SETS_JSON=$(echo "$PS_JSON" | jq -c '[.result.records[] | {developer_name: .Name, id: .Id, label: .Label}]')
+PS_IDS_ARR=$(echo "$PS_JSON" | jq -c '[.result.records[].Id]')
+
+PS_IDS_IN=""
+for pid in $(echo "$PS_IDS_ARR" | jq -r '.[]'); do
+  if [ -n "$PS_IDS_IN" ]; then PS_IDS_IN="$PS_IDS_IN,"; fi
+  PS_IDS_IN="$PS_IDS_IN'$pid'"
+done
+
+EXPECTED_USERNAMES=()
+for i in $(seq 1 "$COUNT"); do
+  EXPECTED_USERNAMES+=("supervisor${i}.${SUFFIX}@example.com")
+done
+
+USER_IN_CLAUSE=""
+for un in "${EXPECTED_USERNAMES[@]}"; do
+  if [ -n "$USER_IN_CLAUSE" ]; then USER_IN_CLAUSE="$USER_IN_CLAUSE,"; fi
+  USER_IN_CLAUSE="$USER_IN_CLAUSE'$un'"
+done
+
+# Only active users are valid assignees; filter IsActive=true so an inactive occupant can't satisfy the count.
+U_JSON=$(sf data query --target-org "$ORG" \
+  --query "SELECT Id, Username FROM User WHERE Username IN ($USER_IN_CLAUSE) AND IsActive=true" \
+  --json 2>/dev/null)
+
+U_COUNT=$(echo "$U_JSON" | jq -r '.result.totalSize // 0')
+if [ "$U_COUNT" -lt "$COUNT" ]; then
+  FOUND=$(echo "$U_JSON" | jq -c '[.result.records[].Username]')
+  emit_blocked \
+    "Expected $COUNT ACTIVE supervisor users matching pattern 'supervisor{1..$COUNT}.$SUFFIX@example.com'; found $U_COUNT active ($FOUND). Provision or reactivate the missing supervisor users, then rerun this skill." \
+    "" "$SUFFIX"
+fi
+
+USERS_JSON=$(echo "$U_JSON" | jq -c '[.result.records[] | {id: .Id, username: .Username}]')
+USER_IDS_ARR=$(echo "$USERS_JSON" | jq -c '[.[].id]')
+
+USER_IDS_IN=""
+for uid in $(echo "$USER_IDS_ARR" | jq -r '.[]'); do
+  if [ -n "$USER_IDS_IN" ]; then USER_IDS_IN="$USER_IDS_IN,"; fi
+  USER_IDS_IN="$USER_IDS_IN'$uid'"
+done
+
+PSA_JSON=$(sf data query --target-org "$ORG" \
+  --query "SELECT Id, AssigneeId, PermissionSetId FROM PermissionSetAssignment WHERE AssigneeId IN ($USER_IDS_IN) AND PermissionSetId IN ($PS_IDS_IN)" \
+  --json 2>/dev/null)
+
+EXISTING_PAIRS=$(echo "$PSA_JSON" | jq -c '[.result.records[] | {user_id: .AssigneeId, permission_set_id: .PermissionSetId}]')
+EXISTING_COUNT=$(echo "$EXISTING_PAIRS" | jq 'length')
+
+EXPECTED_PAIRS=$(jq -n --argjson users "$USERS_JSON" --argjson pss "$PERMISSION_SETS_JSON" \
+  '[$users[] as $u | $pss[] as $p | {user_id: $u.id, username: $u.username, permission_set_id: $p.id, permission_set_developer_name: $p.developer_name}]')
+
+EXPECTED_COUNT=$((COUNT * PS_COUNT))
+
+MISSING_PAIRS=$(jq -n --argjson expected "$EXPECTED_PAIRS" --argjson existing "$EXISTING_PAIRS" \
+  '[$expected[] | . as $e | select($existing | map(select(.user_id == $e.user_id and .permission_set_id == $e.permission_set_id)) | length == 0)]')
+MISSING_COUNT=$(echo "$MISSING_PAIRS" | jq 'length')
+
+# PLAN_ONLY: all detection above is read-only. Report what a --run would do and stop before any write.
+if [ "${PLAN_ONLY:-}" = "1" ]; then
+  if [ "$MISSING_COUNT" -eq 0 ]; then
+    emit_plan "reused" "All $EXPECTED_COUNT (supervisor x permission-set) assignment(s) already present."
+  else
+    emit_plan "action_needed" "Would assign $MISSING_COUNT missing of $EXPECTED_COUNT expected (supervisor x permission-set) pair(s)."
+  fi
+fi
+
+ASSIGNED_THIS_RUN='[]'
+ASSIGNED_COUNT=0
+PARTIAL_ERRORS=()
+
+if [ "$MISSING_COUNT" -gt 0 ]; then
+  for row in $(echo "$MISSING_PAIRS" | jq -c '.[]'); do
+    USER_ID=$(echo "$row"        | jq -r '.user_id')
+    USERNAME=$(echo "$row"       | jq -r '.username')
+    PS_ID=$(echo "$row"          | jq -r '.permission_set_id')
+    PS_DEV_NAME=$(echo "$row"    | jq -r '.permission_set_developer_name')
+
+    POST_STDERR="$(mktemp)"
+    POST_RESULT=$(sf api request rest --target-org "$ORG" \
+      "/services/data/$API_VERSION/sobjects/PermissionSetAssignment" \
+      --method POST \
+      --body "{\"AssigneeId\":\"$USER_ID\",\"PermissionSetId\":\"$PS_ID\"}" 2>"$POST_STDERR" || true)
+
+    POST_SUCCESS=$(echo "$POST_RESULT" | jq -r '.success // false' 2>/dev/null || echo "false")
+
+    if [ "$POST_SUCCESS" = "true" ]; then
+      PSA_ID=$(echo "$POST_RESULT" | jq -r '.id')
+      ASSIGNED_THIS_RUN=$(echo "$ASSIGNED_THIS_RUN" | jq -c \
+        --arg uid "$USER_ID" --arg un "$USERNAME" \
+        --arg psdn "$PS_DEV_NAME" --arg psaid "$PSA_ID" \
+        '. + [{user_id: $uid, username: $un, permission_set_developer_name: $psdn, assignment_id: $psaid}]')
+      ASSIGNED_COUNT=$((ASSIGNED_COUNT + 1))
+    else
+      ERR_CODE=$(echo "$POST_RESULT" | jq -r 'if type == "array" then .[0].errorCode else .errorCode // "UNKNOWN" end' 2>/dev/null || echo "UNKNOWN")
+      ERR_MSG=$(echo "$POST_RESULT"  | jq -r 'if type == "array" then .[0].message   else .message   // "Unknown POST error" end' 2>/dev/null || echo "Unknown POST error")
+
+      if [ "$ERR_CODE" = "UNKNOWN" ] && [ -z "$POST_RESULT" ]; then
+        ERR_MSG=$(grep -v '^Warning:' "$POST_STDERR" | head -1 || echo "sf CLI produced no output")
+      fi
+
+      if [ "$ERR_CODE" = "DUPLICATE_VALUE" ]; then
+        :
+      else
+        PARTIAL_ERRORS+=("$USERNAME ($USER_ID) → $PS_DEV_NAME: $ERR_CODE - $ERR_MSG")
+      fi
+    fi
+    rm -f "$POST_STDERR"
+  done
+fi
+
+AFTER_PSA_JSON=$(sf data query --target-org "$ORG" \
+  --query "SELECT AssigneeId, PermissionSetId FROM PermissionSetAssignment WHERE AssigneeId IN ($USER_IDS_IN) AND PermissionSetId IN ($PS_IDS_IN)" \
+  --json 2>/dev/null)
+
+AFTER_PAIRS=$(echo "$AFTER_PSA_JSON" | jq -c '[.result.records[] | {user_id: .AssigneeId, permission_set_id: .PermissionSetId}]')
+AFTER_COUNT=$(echo "$AFTER_PAIRS" | jq 'length')
+
+REUSED_COUNT=$EXISTING_COUNT
+
+if [ ${#PARTIAL_ERRORS[@]} -gt 0 ] || [ "$AFTER_COUNT" -lt "$EXPECTED_COUNT" ]; then
+  STATUS="partial"
+  BLOCKING_ISSUE="Partial assign: after re-query, $AFTER_COUNT of $EXPECTED_COUNT expected pairs are present. Failures: ${PARTIAL_ERRORS[*]:-"(none; count mismatch only)"}"
+elif [ "$ASSIGNED_COUNT" -eq 0 ]; then
+  STATUS="reused"
+  BLOCKING_ISSUE=""
+else
+  STATUS="assigned"
+  BLOCKING_ISSUE=""
+fi
+
+BLOCKING_JQ_ARG='null'
+if [ -n "$BLOCKING_ISSUE" ]; then
+  BLOCKING_JQ_ARG=$(jq -n --arg s "$BLOCKING_ISSUE" '$s')
+fi
+
+jq -n \
+  --arg status "$STATUS" \
+  --argjson pss "$PERMISSION_SETS_JSON" \
+  --arg suf "$SUFFIX" \
+  --argjson count "$COUNT" \
+  --argjson expected "$EXPECTED_COUNT" \
+  --argjson before_pairs "$EXISTING_PAIRS" \
+  --argjson before_count "$EXISTING_COUNT" \
+  --argjson assigned "$ASSIGNED_THIS_RUN" \
+  --argjson assigned_count "$ASSIGNED_COUNT" \
+  --argjson reused_count "$REUSED_COUNT" \
+  --argjson after_pairs "$AFTER_PAIRS" \
+  --argjson after_count "$AFTER_COUNT" \
+  --argjson blocking "$BLOCKING_JQ_ARG" \
+  '{
+    skill: "service-omni-supervisor-permset-assign",
+    status: $status,
+    permission_sets: $pss,
+    org_suffix: $suf,
+    requested_count: $count,
+    expected_assignment_count: $expected,
+    before: {
+      existing_assignment_pairs: $before_pairs,
+      existing_count: $before_count
+    },
+    assigned_this_run: $assigned,
+    assigned_count: $assigned_count,
+    reused_count: $reused_count,
+    after: {
+      assignment_pairs: $after_pairs,
+      assignment_count: $after_count
+    },
+    manual_actions: [],
+    blocking_issue: $blocking
+  }'

package/skills/service-omni-supervisor-surface-deploy/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: service-omni-supervisor-surface-deploy
+description: "Use to populate the Omni-Channel Supervisor action + tab surface on an existing OmniSupervisorConfig by inserting the standard OmniSupervisorConfigAction and OmniSupervisorConfigTab companion rows via the Data API, idempotent (inserts only the missing types). Requires an OmniSupervisorConfig from service-omni-supervisor-config-deploy. Triggers: give the supervisor the standard action buttons and tabs, add Wallboard/Agents/Queues tabs to Omni Supervisor, configure supervisor actions like Change Queues/Skills. Do not use to create the supervisor configuration itself, create supervisor users, assign the supervisor permission set, or add custom-action / FlexiPage / AWS-dashboard / AI-agent surfaces (those need an external reference and must be set up in Setup)."
+allowed-tools: Bash Read Write Edit Glob Grep
+metadata:
+  version: "1.0"
+  domains: ["Service"]
+  minApiVersion: "66.0"
+  relatedSkills:
+    - "service-omni-command-center-analyze"
+    - "service-omni-supervisor-config-deploy"
+    - "service-omni-supervisor-permset-assign"
+  accessCheck:
+    - type: license
+      value: ServiceCloud
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6"
+    - tool: ["python3"]
+      semver: ">=3.8"
+    - tool: ["sf"]
+      semver: ">=2.139.6"
+---
+
+# service-omni-supervisor-surface-deploy
+
+Populate the Omni-Channel Supervisor **surface** — the action buttons and tabs a supervisor sees — on an existing `OmniSupervisorConfig`. `OmniSupervisorConfigAction` and `OmniSupervisorConfigTab` are createable child sObjects (`OmniSupervisorConfigId`, a `*Type` picklist, and `DisplayOrder`), so the surface is populated with plain Data API inserts against the parent config's Id rather than by re-deploying the whole `OmniSupervisorConfig` metadata document. That keeps this leaf independent of `service-omni-supervisor-config-deploy` (which owns the user/queue companions inside the metadata file) and lets it run idempotently — it inserts only the types that are missing.
+
+## Inputs
+
+`bash scripts/deploy-and-report.sh <org-alias> [config_developer_name]`
+
+- `org-alias` (required) — must resolve via `sf org display --target-org <alias>`.
+- `config_developer_name` (optional) — the `OmniSupervisorConfig.DeveloperName` to populate. Omit it when the org has exactly one config; the skill resolves it. With multiple configs and no name, the skill blocks and lists them.
+
+Env overrides (both CSV of picklist values; defaults are the reference-free standard set):
+
+- `SUPERVISOR_ACTIONS` — default `AllAgents.ChangeQueues,AllAgents.ChangeSkills,AllAgents.ChangeGroups,AllAgents.AssignLearning,QueuesBacklog.ManageQueues`.
+- `SUPERVISOR_TABS` — default `Wallboard,Agents,QueuesBacklog,AssignedWork,SkillsBacklog`.
+- `PLAN_ONLY=1` — report intent (existing vs. requested) and stop before any write.
+
+## Preconditions and safety
+
+- Target org authenticated via `sf` CLI, Service Cloud license present, `sf` CLI ≥ 2.139.6.
+- An `OmniSupervisorConfig` exists — provisioned by `service-omni-supervisor-config-deploy`. If none exists (or the named one is absent), the skill blocks with a `target_skill` pointer.
+- **Production guardrail:** the script computes `safe_to_write` as `IsSandbox` OR `TrialExpirationDate != null` OR `OrganizationType` in {Developer Edition, Base Edition}, and blocks with no override when it is false.
+
+## Run
+
+```bash
+bash scripts/deploy-and-report.sh <org-alias> [config_developer_name]
+```
+
+It resolves the parent config, reads the surface rows already present, inserts only the missing action/tab types (appending `DisplayOrder` after the current maximum), and emits JSON to stdout.
+
+## Behavior
+
+**Reference-free types only.** The companion rows expose no reference field, so only self-contained types can be inserted headlessly. The skill accepts the standard set (`SAFE_ACTIONS` / `SAFE_TABS` in `references/api-notes.md`) and **blocks up front** on any type that needs an external reference — `*.CustomAction`, `*.AWSDashboard`, `FlexipageType`, `AIAgents`, `AgentforceSDR` — pointing you to Setup. Requesting a type outside the supported vocabulary also blocks before any write.
+
+**Idempotency.** The requested types are diffed against the rows already on the config; existing types are reported as `reused` and never re-inserted, missing types are inserted and reported as `created`. `status` is `created` when anything was inserted, otherwise `reused`. Re-running the skill unchanged makes no writes.
+
+**Ordering.** New rows are appended: `DisplayOrder` starts one above the current maximum for that companion type, preserving any ordering already configured in Setup.
+
+## Output contract
+
+A single JSON object to stdout. `status` is one of `created`, `reused`, `blocked`, or (with `PLAN_ONLY=1`) `action_needed`. The object also carries `config` (`developer_name`, `id`), `actions` and `tabs` (each with `requested`, `created`, `reused`, `count`), `manual_actions`, and `blocking_issue` (`null` unless `status: blocked`).
+
+Org-side spot-check:
+
+```sql
+SELECT OmniSupervisorActionType, DisplayOrder FROM OmniSupervisorConfigAction WHERE OmniSupervisorConfigId = :configId ORDER BY DisplayOrder
+SELECT OmniSupervisorTabType,    DisplayOrder FROM OmniSupervisorConfigTab    WHERE OmniSupervisorConfigId = :configId ORDER BY DisplayOrder
+```
+
+## Limitations
+
+- Populates only the reference-free standard action and tab types. Custom actions, FlexiPage tabs, AWS dashboards, and AI-agent surfaces need an external reference and must be configured in Setup.
+- Does not create, rename, or delete the parent `OmniSupervisorConfig`, its user/queue companions, or supervisor users/permission sets.
+- Does not remove surface rows — it only adds missing ones (no destructive reconciliation).
+
+## References
+
+| File | When to read |
+|---|---|
+| `references/api-notes.md` | The full `OmniSupervisorActionType` / `OmniSupervisorTabType` vocabulary, which types are reference-free, and companion-row insert semantics |

package/skills/service-omni-supervisor-surface-deploy/references/api-notes.md

@@ -0,0 +1,47 @@
+# Omni Supervisor surface (Action + Tab) - API notes
+
+## What this leaf writes
+
+Plain Data API inserts, one row per missing type:
+
+- `OmniSupervisorConfigAction` - createable fields: `OmniSupervisorConfigId`, `OmniSupervisorActionType` (picklist), `DisplayOrder`.
+- `OmniSupervisorConfigTab` - createable fields: `OmniSupervisorConfigId`, `OmniSupervisorTabType` (picklist), `DisplayOrder`.
+
+Both are companions of `OmniSupervisorConfig`. Because they are createable child sObjects, the surface is populated without re-deploying the parent `OmniSupervisorConfig` metadata document - that document is owned by `service-omni-supervisor-config-deploy` and carries the user/queue companions. Splitting the surface into a Data API leaf keeps the two skills from fighting over the same whole-document metadata file.
+
+## Why "reference-free types only"
+
+Neither companion exposes a reference field in `describe` (only `OmniSupervisorConfigId`, the `*Type`, and `DisplayOrder` are createable). So a type that needs to point at something external cannot be expressed as a bare row and must be configured in Setup. This leaf blocks up front on:
+
+- Action types matching `*.CustomAction` or `*.AWSDashboard`.
+- Tab types `FlexipageType`, `AIAgents`, `AgentforceSDR`.
+
+## OmniSupervisorActionType vocabulary (org-verified, API 66)
+
+Reference-free (this leaf's `SAFE_ACTIONS`, and the default set):
+
+- `AllAgents.ChangeQueues`
+- `AllAgents.ChangeSkills`
+- `AllAgents.ChangeGroups`
+- `AllAgents.AssignLearning`
+- `QueuesBacklog.ManageQueues`
+
+Reference-required (blocked - configure in Setup): `AllAgents.CustomAction`, `AllAgents.AWSDashboard`, `AgentDetails.CustomAction`, `QueuesBacklog.CustomAction`, `QueuesBacklog.AWSDashboard`, `QueueDetails.CustomAction`, `AssignedWork.CustomAction`, `AssignedWork.AWSDashboard`, `AssignedWorkDetails.CustomAction`, `SkillsBacklog.CustomAction`, `SkillsBacklog.AWSDashboard`, `SkillDetails.CustomAction`.
+
+## OmniSupervisorTabType vocabulary (org-verified, API 66)
+
+Reference-free (this leaf's `SAFE_TABS`): `Wallboard`, `Agents`, `QueuesBacklog`, `AssignedWork`, `SkillsBacklog`, `Reports`, `Alerts`. The default set is the first five (the core supervisor panels); `Reports` and `Alerts` are accepted when requested explicitly.
+
+Reference-required (blocked - configure in Setup): `FlexipageType`, `AIAgents`, `AgentforceSDR`.
+
+## Idempotency and ordering
+
+The requested types are diffed against the rows already on the config (`SELECT OmniSupervisorActionType/OmniSupervisorTabType ... WHERE OmniSupervisorConfigId = :id`). Existing types are reported `reused`; missing types are inserted. New `DisplayOrder` values start one above the current maximum for that companion, so ordering already configured in Setup is preserved and re-runs make no writes.
+
+`DisplayOrder` is not required to be unique across rows; appending after the maximum simply keeps newly added items at the end of the supervisor's list.
+
+## Related
+
+- `service-omni-supervisor-config-deploy` - creates the parent `OmniSupervisorConfig` and its user/queue companions (prerequisite).
+- `service-omni-supervisor-permset-assign` - grants supervisors the `ContactCenterSupervisor` permission set.
+- `service-omni-command-center-analyze` - reports whether the org is on the classic supervisor surface vs. Command Center V2.