@salesforce/afv-skills 1.46.0 → 1.48.0

package/skills/service-omni-skills-based-routing-configure/scripts/tests/test_sbr_contracts.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""Contract tests for service-omni-skills-based-routing-configure/scripts/configure-and-report.sh."""
+from __future__ import annotations
+
+import json
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _bootstrap import (  # noqa: E402
+    FakeSf,
+    _FAKE_SF_PROD,
+    _FAKE_SF_SANDBOX,
+    run,
+)
+
+
+def _last_json(out: str) -> dict:
+    dec = json.JSONDecoder()
+    obj, i, n = None, 0, len(out)
+    while i < n:
+        if out[i] in "{[":
+            try:
+                cand, end = dec.raw_decode(out, i)
+                if isinstance(cand, dict):
+                    obj = cand
+                i = end
+                continue
+            except json.JSONDecodeError:
+                pass
+        i += 1
+    assert obj is not None, f"no JSON object found in output:\n{out}"
+    return obj
+
+
+class InputContractTests(unittest.TestCase):
+    def test_missing_args_rejected(self):
+        rc, out = run(["myorg"], scrub_sf=True)
+        self.assertEqual(rc, 1, out)
+        self.assertIn("Usage", out)
+
+    def test_injection_shaped_skill_name_rejected(self):
+        rc, out = run(["myorg", "Bad Skill; DROP", "a@b.com"], scrub_sf=True)
+        self.assertEqual(rc, 1, out)
+        self.assertIn("Invalid skill_developer_name", out)
+
+    def test_missing_agents_rejected(self):
+        rc, out = run(["myorg", "Omni_Demo_Voice"], scrub_sf=True)
+        self.assertEqual(rc, 1, out)
+        self.assertIn("No agents supplied", out)
+
+
+class ProductionGuardTests(unittest.TestCase):
+    def test_refuses_production_org(self):
+        with FakeSf(_FAKE_SF_PROD) as p:
+            rc, out = run(["prodorg", "Omni_Demo_Voice", "agent1@example.com"], path_prefix=p)
+        self.assertEqual(rc, 1, out)
+        v = _last_json(out)
+        self.assertEqual(v["status"], "blocked", out)
+        self.assertIn("production", v["blocking_issue"].lower())
+
+
+class ConfigureTests(unittest.TestCase):
+    def test_full_create_deploys_skill_and_binds(self):
+        with FakeSf(_FAKE_SF_SANDBOX) as p:
+            rc, out = run(["sandbox", "Omni_Demo_Voice", "agent1@example.com,agent2@example.com"],
+                          path_prefix=p, extra_env={"FAKE_SKILL_PRESENT": "0", "FAKE_BIND_PRESENT": "0"})
+        self.assertEqual(rc, 0, out)
+        v = _last_json(out)
+        self.assertEqual(v["status"], "configured", out)
+        self.assertEqual(v["skill_configured"]["state"], "created", out)
+        self.assertEqual(v["created_counts"]["skill_bindings"], 2, out)
+        self.assertNotIn("service_resources", v["created_counts"], out)
+        self.assertTrue(all("skill_binding_id" in agent for agent in v["agents"]), out)
+
+    def test_reused_when_all_present_no_writes(self):
+        with FakeSf(_FAKE_SF_SANDBOX) as p:
+            calllog = str(Path(p) / "calls.log")
+            rc, out = run(["sandbox", "Omni_Demo_Voice", "agent1@example.com,agent2@example.com"],
+                          path_prefix=p, extra_env={"FAKE_SKILL_PRESENT": "1", "FAKE_BIND_PRESENT": "1",
+                                                     "FAKE_SF_CALLLOG": calllog})
+            log = Path(calllog).read_text() if Path(calllog).exists() else ""
+        self.assertEqual(rc, 0, out)
+        v = _last_json(out)
+        self.assertEqual(v["status"], "reused", out)
+        self.assertNotIn("project deploy", log, "reused must not deploy the skill")
+        self.assertNotIn("--method POST", log, "reused must not create bindings")
+
+    def test_partial_when_one_binding_post_fails(self):
+        with FakeSf(_FAKE_SF_SANDBOX) as p:
+            rc, out = run(["sandbox", "Omni_Demo_Voice", "agent1@example.com,agent2@example.com"],
+                          path_prefix=p, extra_env={"FAKE_SKILL_PRESENT": "1", "FAKE_BIND_PRESENT": "0",
+                                                     "FAKE_BIND_POST_FAIL": "1"})
+        self.assertEqual(rc, 0, out)
+        v = _last_json(out)
+        self.assertEqual(v["status"], "partial", out)
+        self.assertIn("skill binding failed", v["blocking_issue"])
+        self.assertEqual(v["created_counts"]["skill_bindings"], 1, out)
+
+    def test_duplicate_value_is_treated_as_reused(self):
+        with FakeSf(_FAKE_SF_SANDBOX) as p:
+            rc, out = run(["sandbox", "Omni_Demo_Voice", "agent1@example.com,agent2@example.com"],
+                          path_prefix=p, extra_env={"FAKE_SKILL_PRESENT": "1", "FAKE_BIND_PRESENT": "0",
+                                                     "FAKE_BIND_DUPLICATE": "1"})
+        self.assertEqual(rc, 0, out)
+        v = _last_json(out)
+        self.assertIsNone(v["blocking_issue"], out)
+        self.assertNotEqual(v["status"], "partial", out)
+        self.assertEqual(v["created_counts"]["skill_bindings"], 0, out)
+        self.assertEqual(v["reused_counts"]["skill_bindings"], 2, out)
+
+    def test_plan_only_reports_without_writing(self):
+        with FakeSf(_FAKE_SF_SANDBOX) as p:
+            calllog = str(Path(p) / "calls.log")
+            rc, out = run(["sandbox", "Omni_Demo_Voice", "agent1@example.com"],
+                          path_prefix=p, extra_env={"FAKE_SKILL_PRESENT": "0", "PLAN_ONLY": "1",
+                                                     "FAKE_SF_CALLLOG": calllog})
+            log = Path(calllog).read_text() if Path(calllog).exists() else ""
+        self.assertEqual(rc, 0, out)
+        v = _last_json(out)
+        self.assertTrue(v.get("plan_mode"), out)
+        self.assertEqual(v["status"], "action_needed", out)
+        self.assertNotIn("project deploy", log, "plan mode must not deploy")
+        self.assertNotIn("--method POST", log, "plan mode must not POST")
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

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

@@ -0,0 +1,97 @@
+---
+name: service-omni-supervisor-config-deploy
+description: "Use to stand up a headless Omni-Channel Supervisor Configuration by deploying the classic OmniSupervisorConfig (parent plus supervisor-user and queue companions) in one atomic Metadata API deploy, idempotent via the deploy state. Requires active supervisor users, Omni base settings, and the monitored queues. Triggers: set up Omni Supervisor, configure the classic Supervisor Command Center. Do not use to create supervisor users, assign the ContactCenterSupervisor permission set, or deploy queues, service channels, or presence statuses."
+allowed-tools: Bash Read Write Edit Glob Grep
+metadata:
+  version: "1.0"
+  domains: ["Service"]
+  minApiVersion: "66.0"
+  relatedSkills:
+    - "service-omni-agent-work-sharing-configure"
+    - "service-omni-base-settings-configure"
+    - "service-omni-channel-setup-coordinate"
+    - "service-omni-presence-status-deploy"
+    - "service-omni-queue-deploy"
+    - "service-omni-service-channel-configure"
+    - "service-omni-supervisor-permset-assign"
+    - "service-omni-supervisor-surface-deploy"
+  accessCheck:
+    - type: license
+      value: ServiceCloud
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6"
+    - tool: ["python3"]
+      semver: ">=3.9"
+    - tool: ["sf"]
+      semver: ">=2.139.6"
+---
+
+# service-omni-supervisor-config-deploy
+
+Deploy the classic Omni-Channel Supervisor Configuration (`OmniSupervisorConfig`) to a Salesforce org in a single Metadata API deploy. `OmniSupervisorConfig` is a full Metadata API type whose XSD embeds every companion as a repeatable child element, so the whole configuration — parent plus companions — lands atomically from one `.omniSupervisorConfig-meta.xml` file, and Salesforce rolls the companions back together on a partial failure. By default the deploy binds supervisors explicitly by user and lists the queues they monitor; profile scope is optional (see Behavior).
+
+## Inputs
+
+`bash scripts/deploy-and-report.sh <org-alias> [supervisor_count] [additional_queues_csv] [profiles_csv] [skill_visibility] [config_developer_name]`
+
+- `org-alias` (required) — must resolve via `sf org display --target-org <alias>`.
+- `supervisor_count` (optional, default `1`, range `1..5`) — how many active `supervisor{N}.<suffix>@example.com` users to detect and bind.
+- `additional_queues_csv` (optional) — queue DeveloperNames to bind. When the coordinator supplies this list it is authoritative; when omitted, the canonical `CaseQueue`, `messagingqueue` defaults are used. Every requested queue must already exist on the org.
+- `profiles_csv` (optional) — opt into profile-based fallback scope; supply metadata profile fullNames (e.g. `Standard,ServiceCloud`). Omit it to bind supervisors by user only.
+- `skill_visibility` (optional, or `OMNI_SUPERVISOR_SKILL_VISIBILITY`) — `AllSkills` or `AnySkill`. Omitted values preserve an existing config's selection; a new config defaults to `AllSkills`.
+- `config_developer_name` (optional, or `OMNI_SUPERVISOR_CONFIG_DEVELOPER_NAME`; default `Omni_Supervisor`) — the exact classic `OmniSupervisorConfig.DeveloperName` to create or reconcile. Supply it when an org has multiple supervisor configurations; the skill never guesses between candidates. `OMNI_SUPERVISOR_CONFIG_MASTER_LABEL` optionally sets the label for a new config. Existing labels are preserved by default.
+
+## Preconditions and safety
+
+- Target org authenticated via `sf` CLI, Service Cloud license present, `sf` CLI ≥ 2.139.6.
+- Active supervisor users exist; their supervisor access is granted separately by `service-omni-supervisor-permset-assign`.
+- Omni-Channel base settings are enabled (`service-omni-base-settings-configure`) and the monitored queues exist (`service-omni-queue-deploy`).
+- **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. Any unmet precondition returns `status: blocked` with a `blocking_issue` and a click-path.
+
+## Run
+
+One script does detect, deploy, and verify:
+
+```bash
+bash scripts/deploy-and-report.sh <org-alias> [supervisor_count] [additional_queues_csv] [profiles_csv] [skill_visibility] [config_developer_name]
+```
+
+It resolves the deploy artifact's tokens from live org state (discovered supervisor users, verified queues, and — only when `profiles_csv` is given — validated profiles), materializes the selected DeveloperName into the metadata filename and package manifest, then re-queries that same selected config to confirm the parent and its companion rows persisted before emitting JSON to stdout. The coordinator (`service-omni-channel-setup-coordinate`) invokes it with the authoritative queue list and selected supervisor config; standalone runs use the canonical defaults.
+
+## Behavior
+
+**Companions.** The deployed config always carries `omniSupervisorConfigUser` (one per supervisor) and `omniSupervisorConfigQueue` (one per monitored queue). It follows the same single-file Metadata deploy shape as `service-omni-service-channel-configure` and `service-omni-presence-status-deploy`.
+
+**Profile scope is a fallback, off by default.** Core resolves a supervisor's configuration by `OmniSupervisorConfigUser` first, and only falls back to `OmniSupervisorConfigProfile` — matched against *that supervisor's own profile* — when the supervisor has no user row (`RealTimeQueueServiceImpl.getSupervisorConfigId`). Because this skill binds every supervisor by user, profile companions are unnecessary and are omitted unless you pass `profiles_csv`. When supplied, values must be metadata fullNames (the `<profile>` element resolves against the fullName — `Standard`, `ServiceCloud`, `Admin` — not the SOQL `User.Profile.Name` label); the skill validates each against `sf org list metadata -m Profile` and blocks on any the org does not expose.
+
+**Idempotency and surface preservation.** Status follows the Metadata deploy component state: `Unchanged` → `reused`, `Changed` → `updated`, `Created` → `created`. Any other state is a hard failure rather than a silent `reused`. Before updating an existing parent, the skill snapshots its reference-free `OmniSupervisorConfigAction` and `OmniSupervisorConfigTab` rows, validates that each can be recreated safely, then restores and re-queries them after the deploy. A custom/reference-bearing surface blocks before deployment instead of risking silent loss. When reconciling an existing config or verifying preservation, invoke only this skill; do not invoke `service-omni-supervisor-surface-deploy`, because adding standard rows afterward could mask a preservation failure. The companion surface skill remains responsible only for a separate request to add new standard actions or tabs.
+
+**Fail-closed verification.** The deploy `status` must be `Succeeded` (not `SucceededPartial`). After the parent config is queryable, the script re-queries the child `OmniSupervisorConfigUser` and `OmniSupervisorConfigQueue` rows and requires at least the intended counts — the parent existing does not prove the companions landed. Every read must return a parseable `.result.records` array; an inconclusive read never counts as zero. Requested queues are validated against `^[A-Za-z0-9_]{1,80}$` before use, and every requested queue must exist or the run blocks (dropping one silently would under-provision the config).
+
+## Output contract
+
+A single JSON object to stdout. `status` is one of `created`, `updated`, `reused`, or `blocked`. The object also carries `config_developer_name`, `config_id`, `skill_visibility`, `surface_preservation` snapshot/restoration counts, `supervisor_users_bound`/`supervisor_users_count`, `queues_bound`/`queues_count`, `queue_source` (`caller_supplied` or `canonical_default`), the re-queried `verified_companion_user_count`/`verified_companion_queue_count`, `deploy_id`, `state`, `manual_actions`, and `blocking_issue`. `blocking_issue` is `null` unless `status: blocked`, in which case it names the missing prerequisite with a click-path in `manual_actions`. Re-running an unchanged config returns `reused` and performs no functional change.
+
+Org-side spot-check:
+
+```sql
+SELECT Id, DeveloperName, MasterLabel FROM OmniSupervisorConfig WHERE DeveloperName='<config_developer_name>'
+SELECT COUNT(Id) FROM OmniSupervisorConfigUser  WHERE OmniSupervisorConfigId = :configId
+SELECT COUNT(Id) FROM OmniSupervisorConfigQueue WHERE OmniSupervisorConfigId = :configId
+```
+
+## Limitations
+
+- Populates user and queue companions (plus optional profile scope). Existing reference-free Action and Tab rows are preserved across an update; new standard rows are added separately by `service-omni-supervisor-surface-deploy`. Custom-action, FlexiPage, AWS-dashboard, and AI-agent rows require external references and therefore block an update rather than being reconstructed incompletely.
+- Binds supervisor users discovered by the `supervisor{N}.<suffix>@example.com` pattern; it does not create them.
+- Does not change AgentWork sharing because that org-wide access control is separate from `OmniSupervisorConfig`. Use `service-omni-agent-work-sharing-configure` for supported metadata detection and the explicitly confirmed `Private` to `Read` operation.
+- Does not activate the Command Center V2 runtime (a separate settings flip).
+
+## References
+
+| File | When to read |
+|---|---|
+| `references/api-notes.md` | On a deploy failure — field-by-field `OmniSupervisorConfig` schema and companion sObject semantics |
+| `assets/force-app/main/default/omniSupervisorConfigs/Omni_Supervisor.omniSupervisorConfig-meta.xml` | The token-templated deploy artifact (`__MASTER_LABEL__`, `__SUPERVISOR_USERS_XML__`, `__PROFILE_SCOPE_XML__`, `__QUEUE_LIST_XML__`, `__SKILL_VISIBILITY__`); it is materialized under the selected DeveloperName at runtime |
+| `assets/package.xml`, `assets/sfdx-project.json` | Manifest and project scaffold materialized into the temp deploy dir |

package/skills/service-omni-supervisor-config-deploy/assets/force-app/main/default/omniSupervisorConfigs/Omni_Supervisor.omniSupervisorConfig-meta.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<OmniSupervisorConfig xmlns="http://soap.sforce.com/2006/04/metadata">
+    <isTimelineHidden>false</isTimelineHidden>
+    <masterLabel>__MASTER_LABEL__</masterLabel>
+    __PROFILE_SCOPE_XML__
+    __QUEUE_LIST_XML__
+    __SUPERVISOR_USERS_XML__
+    <skillVisibility>__SKILL_VISIBILITY__</skillVisibility>
+</OmniSupervisorConfig>

package/skills/service-omni-supervisor-config-deploy/assets/package.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Package xmlns="http://soap.sforce.com/2006/04/metadata">
+    <types>
+        <members>Omni_Supervisor</members>
+        <name>OmniSupervisorConfig</name>
+    </types>
+    <version>66.0</version>
+</Package>

package/skills/service-omni-supervisor-config-deploy/assets/sfdx-project.json

@@ -0,0 +1,12 @@
+{
+  "packageDirectories": [
+    {
+      "path": "force-app",
+      "default": true
+    }
+  ],
+  "name": "service-omni-supervisor-config-deploy",
+  "namespace": "",
+  "sfdcLoginUrl": "https://login.salesforce.com",
+  "sourceApiVersion": "66.0"
+}

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

@@ -0,0 +1,205 @@
+# OmniSupervisorConfig — API notes
+
+Load this reference **only when the deploy fails or Salesforce reports unexpected state**. Under normal operation the skill's `deploy-and-report.sh` just runs and emits its JSON; this doc is for troubleshooting and future extensions.
+
+**Metadata type:** `OmniSupervisorConfig` (dir `omniSupervisorConfigs`, suffix `omniSupervisorConfig`)
+**API version:** v66. **Available in the Metadata API since:** v57 (Winter '23).
+
+---
+
+## Why Metadata deploy (not REST POST)
+
+`OmniSupervisorConfig` is a Metadata API type (since v57), so this skill deploys it as metadata rather than driving a REST POST loop per companion. Every companion sObject (User/Group/Profile/Queue/Skill/Action/Tab) embeds inside the parent as `maxOccurs="unbounded"` elements per the Metadata SOAP XSD.
+
+Trade-off analysis:
+
+| Dimension | REST POST (per-companion loop) | Metadata deploy (this skill) |
+|-----------|-----------------|------------------------------|
+| API calls | 8+ (1 parent + N companion POSTs) | 1 |
+| Idempotency logic | Custom SOQL detect + skip in script | Platform-managed via `state:Unchanged` |
+| Atomicity | Partial state on mid-flight failure | All or nothing |
+| Source control | Detect scripts + JSON payloads | Single XML file, diff-friendly |
+| Rollback | Manual cleanup on error | Automatic |
+| Skill script size | ~200 lines | ~150 lines (mostly per-org discovery) |
+| Alignment with other skills | Different pattern | Same as ServiceChannel and PresenceStatus skills |
+
+---
+
+## Metadata SOAP XSD (v66, from core/shared/submodules/wsdl)
+
+```xml
+<xsd:complexType name="OmniSupervisorConfig">
+  <xsd:extension base="mns:Metadata">
+    <xsd:sequence>
+      <xsd:element name="isTimelineHidden" type="xsd:boolean"/>
+      <xsd:element name="masterLabel" type="xsd:string"/>
+      <xsd:element maxOccurs="unbounded" minOccurs="0" name="omniSpvsrConfigAIAgent" type="mns:OmniSpvsrConfigAIAgent"/>
+      <xsd:element maxOccurs="unbounded" minOccurs="0" name="omniSupervisorConfigAction" type="mns:OmniSupervisorConfigAction"/>
+      <xsd:element maxOccurs="unbounded" minOccurs="0" name="omniSupervisorConfigGroup" type="mns:OmniSupervisorConfigGroup"/>
+      <xsd:element maxOccurs="unbounded" minOccurs="0" name="omniSupervisorConfigProfile" type="mns:OmniSupervisorConfigProfile"/>
+      <xsd:element maxOccurs="unbounded" minOccurs="0" name="omniSupervisorConfigQueue" type="mns:OmniSupervisorConfigQueue"/>
+      <xsd:element maxOccurs="unbounded" minOccurs="0" name="omniSupervisorConfigSkill" type="mns:OmniSupervisorConfigSkill"/>
+      <xsd:element maxOccurs="unbounded" minOccurs="0" name="omniSupervisorConfigTab" type="mns:OmniSupervisorConfigTab"/>
+      <xsd:element maxOccurs="unbounded" minOccurs="0" name="omniSupervisorConfigUser" type="mns:OmniSupervisorConfigUser"/>
+      <xsd:element minOccurs="0" name="skillVisibility" type="tns:OmniSuperSkillVisibilityType"/>
+    </xsd:sequence>
+  </xsd:extension>
+</xsd:complexType>
+```
+
+## Companion field definitions (all verified against v66 SOAP XSD)
+
+| Companion | Fields | Notes |
+|-----------|--------|-------|
+| `omniSupervisorConfigUser` | `user` (Username) | Which supervisor(s) this config applies to |
+| `omniSupervisorConfigQueue` | `queue` (Queue DeveloperName) | Queues shown in supervisor's queue-monitoring panel |
+| `omniSupervisorConfigProfile` | `profile` (Profile **metadata fullName**, NOT the SOQL `User.Profile.Name` label — see note below) | Agent profiles the supervisor can see |
+| `omniSupervisorConfigGroup` | `group` (Public Group DeveloperName) | Agent group scope (optional, we omit) |
+| `omniSupervisorConfigSkill` | `skill` (Skill DeveloperName) | Skills the supervisor can filter by (optional, we omit) |
+| `omniSupervisorConfigAction` | `actionName` (enum), `actionTab` (enum), `customActionFlow` (string, optional), `displayOrder` (int) | Which action buttons render; enums NOT yet exhaustively documented — v1 omits, uses platform defaults |
+| `omniSupervisorConfigTab` | `displayOrder` (int), `flexiPage` (string, optional), `tabType` (enum) | Which tabs show; enums NOT yet exhaustively documented — v1 omits, uses platform defaults |
+
+**Important:** `omniSpvsrConfigAIAgent` also embeds but requires bots enabled + UDD 256-era APIs. Kept out of scope until we have a bot to bind.
+
+---
+
+## The canonical template shipped by this skill
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<OmniSupervisorConfig xmlns="http://soap.sforce.com/2006/04/metadata">
+    <masterLabel>Omni Supervisor Config</masterLabel>
+    <isTimelineHidden>false</isTimelineHidden>
+    <skillVisibility>All</skillVisibility>
+    <omniSupervisorConfigUser>
+        <user>{supervisor_username}</user>
+    </omniSupervisorConfigUser>
+    <omniSupervisorConfigProfile>
+        <profile>Standard</profile>  <!-- metadata fullName; NOT the "Standard User" label -->
+    </omniSupervisorConfigProfile>
+    <omniSupervisorConfigQueue>
+        <queue>CaseQueue</queue>
+    </omniSupervisorConfigQueue>
+    <omniSupervisorConfigQueue>
+        <queue>messagingqueue</queue>
+    </omniSupervisorConfigQueue>
+</OmniSupervisorConfig>
+```
+
+`__SUPERVISOR_USERS_XML__` gets replaced with 1..N `<omniSupervisorConfigUser>` blocks (per `supervisor_count`).
+`__QUEUE_LIST_XML__` gets replaced with 1..N `<omniSupervisorConfigQueue>` blocks (canonical + `additional_queues_csv`).
+
+---
+
+## Idempotency contract
+
+Salesforce Metadata deploy response `files[].state` field:
+
+| `state` | Meaning | Skill-level `status` |
+|---------|---------|---------------------|
+| `Unchanged` | Payload matched org state byte-for-byte | `reused` |
+| `Changed` | Config existed, some fields differed and were updated | `updated` |
+| `Created` | Config did not exist, freshly created | `created` |
+| `Failed` / other | Deploy did not succeed | `blocked` |
+
+Re-running with no template drift returns `status: reused` in ~3 seconds. Adding a new supervisor to the org and re-running returns `status: updated` (adds the companion binding); no need to detect-before-POST because the template regeneration handles the delta.
+
+---
+
+## Common failure modes
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| `INVALID_TYPE: OmniSupervisorConfig` on deploy | Deploying against pre-v57 org | Bump target `sourceApiVersion` to 57.0+ (v66 recommended) |
+| `INVALID_FIELD: <fieldname>` on companion | Guessed enum value (actionName / tabType) | v1 template omits action + tab elements; if adding, retrieve a working config from another org first |
+| `DUPLICATE_VALUE` on User binding | Same user already bound to another OmniSupervisorConfig | Salesforce allows one supervisor per config; if binding to multiple configs needed, split into separate configs |
+| `INVALID_PERSON_OR_GROUP_ID` on queue | Queue DeveloperName typo or queue absent | Verify with: `sf data query -q "SELECT DeveloperName FROM Group WHERE Type='Queue'"` |
+| Deploy hangs > 10 min | Retry storm or org load issue | Retrieve deploy status: `sf project deploy report --job-id <id>` |
+
+---
+
+## Post-deploy SOQL verification
+
+```sql
+-- 1. Config exists
+SELECT Id, DeveloperName, MasterLabel, CreatedDate
+FROM OmniSupervisorConfig
+WHERE DeveloperName='Omni_Supervisor'
+
+-- 2. Supervisor bindings
+SELECT UserId, User.Username
+FROM OmniSupervisorConfigUser
+WHERE OmniSupervisorConfigId IN (SELECT Id FROM OmniSupervisorConfig WHERE DeveloperName='Omni_Supervisor')
+
+-- 3. Queue bindings
+SELECT QueueId, Queue.DeveloperName
+FROM OmniSupervisorConfigQueue
+WHERE OmniSupervisorConfigId IN (SELECT Id FROM OmniSupervisorConfig WHERE DeveloperName='Omni_Supervisor')
+
+-- 4. Profile scope
+SELECT ProfileId, Profile.Name
+FROM OmniSupervisorConfigProfile
+WHERE OmniSupervisorConfigId IN (SELECT Id FROM OmniSupervisorConfig WHERE DeveloperName='Omni_Supervisor')
+```
+
+Expected: 1 config, N supervisor bindings (matches `supervisor_count`), M queue bindings (matches `ALL_QUEUES` after discovery filter), and 1+ profile scope rows (one per resolved agent profile).
+
+## Profile fullName vs. User.Profile.Name
+
+The `<profile>` element resolves against a profile's **metadata fullName**, which for standard profiles differs from the SOQL `User.Profile.Name` label:
+
+| `User.Profile.Name` (SOQL label) | Metadata `<profile>` fullName |
+|----------------------------------|-------------------------------|
+| `Standard User`                  | `Standard`                    |
+| `Service Cloud`                  | `ServiceCloud`                |
+| `System Administrator`           | `Admin`                       |
+| Custom profiles                  | same as the profile Name      |
+
+Deploying a raw SOQL label fails with `In field: profile - no Profile named <label> found`. Profile companions are optional (omitted by default, since supervisors are bound by user); when you pass `profiles_csv`, supply metadata fullNames and `deploy-and-report.sh` validates each against `sf org list metadata -m Profile`, blocking on any the org does not expose. Get the exact fullNames for an org with:
+
+```bash
+sf org list metadata -m Profile -o <org> --json | jq -r '.result[].fullName'
+```
+
+## Idempotency signal
+
+`deploy-and-report.sh` maps the Metadata deploy component state to the skill status: `Unchanged` → `reused`, `Changed` → `updated`, `Created` → `created`. Any unrecognized state blocks rather than silently reporting `reused`. The `config_id` is stable across runs and no companion rows are duplicated on redeploy.
+
+---
+
+## Deploy robustness — async + poll (not synchronous `--wait`)
+
+`OmniSupervisorConfig` deploys are done **async**, then polled to a terminal state:
+
+```bash
+id=$(sf project deploy start --manifest package.xml --target-org "$ORG" --async --json | jq -r '.result.id')
+# poll until Succeeded | Failed | SucceededPartial | Canceled (each report call returns immediately)
+sf project deploy report --job-id "$id" --target-org "$ORG" --json
+```
+
+**Why not `--wait N`:** under heavy CDO load a synchronous `sf project deploy start --wait` can raise
+`ClientTimeoutError` and exit non-zero even though the server-side deploy succeeds — a false failure.
+Async start returns a job id instantly; polling `deploy report` in a loop means no single CLI call
+can client-timeout, so the terminal server-side status is always the authority. Budget the poll loop
+above the slowest deploy/retrieve you expect on a loaded org — the script uses ~20 min.
+
+## Post-deploy verify — bounded retry with backoff
+
+The deploy async+poll above protects the *deploy*; the post-deploy **verification** SOQL reads
+(config_id fetch + companion `OmniSupervisorConfigUser`/`OmniSupervisorConfigQueue` counts) are the
+remaining latency-fragile step. A slow/dropped query, or the just-persisted record/child rows not
+yet visible, could otherwise flip an otherwise-successful deploy to blocked. Each verification read is therefore wrapped in a
+**bounded retry loop with backoff** (5 attempts, 10→40s increasing sleeps): retry while the read is
+inconclusive (not a parseable records array) *or* the count is still below what the deploy was asked
+to bind, then fall through to the existing guards. **Fail-closed is preserved**: after the budget,
+an inconclusive read still blocks, an empty/missing config Id still blocks, and a short companion
+count still blocks as under-provisioned — retries only survive transient org latency, they never
+manufacture success.
+
+## Possible extensions
+
+1. **Add a default action bar** — retrieve a working config from a full CDO to get valid `actionName` / `actionTab` enum values, then bake them into the template.
+2. **Add a default tab list** — same as above for `tabType` enum values.
+3. **Support `omniSupervisorConfigGroup`** — scope by Public Group in addition to profile.
+4. **Support `omniSupervisorConfigSkill`** — scope by Skill for skill-based supervisors.
+5. **Support `omniSpvsrConfigAIAgent`** — bind an Agentforce agent once one is available on the org.