@salesforce/afv-skills 1.55.0 → 1.56.0

package/skills/service-omni-channel-limits-analyze/scripts/analyze.sh

@@ -0,0 +1,159 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  echo "Usage: bash analyze.sh <org-alias> [--routing-model enhanced|legacy] [--max-psrs <1-1000000>]" >&2
+}
+
+ROUTING_MODEL="enhanced"
+MAX_PSRS=""
+MAX_SOURCE="reference_default"
+ORG=""
+
+emit_blocked() {
+  local issue="$1"
+  jq -n \
+    --arg model "$ROUTING_MODEL" \
+    --arg issue "$issue" \
+    '{
+      skill: "service-omni-channel-limits-analyze",
+      status: "blocked",
+      routing_model: $model,
+      metrics: null,
+      caveats: [],
+      blocking_issue: $issue
+    }'
+}
+
+if [ $# -lt 1 ]; then
+  usage
+  exit 1
+fi
+
+ORG="$1"
+shift
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --routing-model)
+      if [ $# -lt 2 ]; then
+        usage
+        exit 1
+      fi
+      ROUTING_MODEL=$(printf '%s' "$2" | tr '[:upper:]' '[:lower:]')
+      if [ "$ROUTING_MODEL" != "enhanced" ] && [ "$ROUTING_MODEL" != "legacy" ]; then
+        emit_blocked "Unsupported routing model '$2'. Use enhanced or legacy."
+        exit 1
+      fi
+      shift 2
+      ;;
+    --max-psrs)
+      if [ $# -lt 2 ] || ! [[ "$2" =~ ^[0-9]+$ ]] || [ "$2" -lt 1 ] || [ "$2" -gt 1000000 ]; then
+        emit_blocked "max-psrs must be an integer from 1 through 1000000."
+        exit 1
+      fi
+      MAX_PSRS="$2"
+      MAX_SOURCE="admin_supplied"
+      shift 2
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+if [ -z "$MAX_PSRS" ]; then
+  if [ "$ROUTING_MODEL" = "enhanced" ]; then
+    MAX_PSRS="300000"
+  else
+    MAX_PSRS="200000"
+  fi
+fi
+
+if ! FORCE_COLOR=0 sf org display --target-org "$ORG" --json >/dev/null 2>&1; then
+  emit_blocked "The target org is not authenticated or cannot be reached. Authenticate it with Salesforce CLI and retry."
+  exit 1
+fi
+
+WORK_DIR=$(mktemp -d "${TMPDIR:-/tmp}/omni-channel-limits.XXXXXX")
+trap 'rm -rf "$WORK_DIR"' EXIT
+RAW_OUTPUT="$WORK_DIR/query-output.txt"
+QUERY_JSON="$WORK_DIR/query.json"
+ERROR_OUTPUT="$WORK_DIR/query-error.txt"
+QUERY="SELECT COUNT() FROM PendingServiceRouting"
+
+if ! FORCE_COLOR=0 sf data query \
+  --query "$QUERY" \
+  --target-org "$ORG" \
+  --json >"$RAW_OUTPUT" 2>"$ERROR_OUTPUT"; then
+  sed -n '/^[[:space:]]*{/,$p' "$RAW_OUTPUT" >"$QUERY_JSON"
+  QUERY_ERROR=$(jq -r '.name // .message // empty' "$QUERY_JSON" 2>/dev/null || true)
+  if printf '%s' "$QUERY_ERROR" | grep -qiE 'INVALID_TYPE|not supported'; then
+    emit_blocked "PendingServiceRouting is unavailable. Confirm Omni-Channel is enabled and the running user can access the object; usage was not treated as zero."
+  elif printf '%s' "$QUERY_ERROR" | grep -qiE 'insufficient|permission|access denied|forbidden'; then
+    emit_blocked "The PendingServiceRouting query was denied. Run the analysis as a user with permission to view Omni routing records."
+  else
+    emit_blocked "The PendingServiceRouting query failed. Verify org connectivity, feature availability, and permissions, then retry."
+  fi
+  exit 1
+fi
+
+sed -n '/^[[:space:]]*{/,$p' "$RAW_OUTPUT" >"$QUERY_JSON"
+if ! jq -e '.status == 0 and (.result | type == "object")' "$QUERY_JSON" >/dev/null 2>&1; then
+  emit_blocked "The PendingServiceRouting query returned an unsupported response. No usage was inferred."
+  exit 1
+fi
+
+CURRENT_PSRS=$(jq -r '.result.records[0].expr0 // .result.totalSize // empty' "$QUERY_JSON")
+if ! [[ "$CURRENT_PSRS" =~ ^[0-9]+$ ]]; then
+  emit_blocked "The PendingServiceRouting query did not return a valid count. No usage was inferred."
+  exit 1
+fi
+
+USAGE_PERCENT=$(jq -n \
+  --argjson current "$CURRENT_PSRS" \
+  --argjson maximum "$MAX_PSRS" \
+  '($current * 10000 / $maximum | round) / 100')
+
+jq -n \
+  --arg model "$ROUTING_MODEL" \
+  --argjson current "$CURRENT_PSRS" \
+  --argjson maximum "$MAX_PSRS" \
+  --argjson usage "$USAGE_PERCENT" \
+  --arg max_source "$MAX_SOURCE" \
+  '{
+    skill: "service-omni-channel-limits-analyze",
+    status: "analyzed",
+    routing_model: $model,
+    metrics: {
+      current_pending_service_routings: {
+        used: $current,
+        limit: $maximum,
+        usage_percent: $usage,
+        used_source: "live_soql",
+        limit_source: $max_source,
+        limit_verified_by_api: false,
+        usage_is_approximate: true
+      },
+      pending_service_routing_rate_per_hour: {
+        used: null,
+        limit: 45000,
+        usage_percent: null,
+        used_source: "not_available_via_supported_api",
+        limit_source: "reference_default",
+        limit_verified_by_api: false
+      }
+    },
+    caveats: [
+      "The PSR count is a point-in-time live query.",
+      "The PSR maximum is not API-verified; it is an administrator-supplied value or a routing-model reference default.",
+      "Live hourly usage is not exposed by a supported customer-org API and was not inferred.",
+      "No org configuration was changed."
+    ],
+    blocking_issue: null
+  }'

package/skills/service-omni-channel-limits-analyze/scripts/tests/_bootstrap.py

@@ -0,0 +1,87 @@
+"""Fake Salesforce CLI harness for the Omni-Channel limits analyzer."""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+SKILLS_ROOT = Path(__file__).resolve().parents[3]
+SCRIPT = SKILLS_ROOT / "service-omni-channel-limits-analyze/scripts/analyze.sh"
+
+_FAKE_SF = r'''#!/usr/bin/env bash
+command_name="${1:-} ${2:-}"
+case "$command_name" in
+  "org display")
+    if [ "${FAKE_AUTH:-ok}" = "fail" ]; then
+      echo '{"status":1,"message":"not authenticated"}' >&2
+      exit 1
+    fi
+    echo '{"status":0,"result":{}}'
+    ;;
+  "data query")
+    printf '%s\n' "$*" >> "${FAKE_SF_LOG:?}"
+    if [ -n "${FAKE_QUERY_BODY:-}" ]; then
+      printf '%s\n' "$FAKE_QUERY_BODY"
+    else
+      printf '%s\n' '{"status":0,"result":{"totalSize":2,"records":[]}}'
+    fi
+    if [ "${FAKE_QUERY_STATUS:-ok}" = "fail" ]; then
+      exit 1
+    fi
+    ;;
+  *)
+    echo '{"status":1,"message":"unexpected command"}' >&2
+    exit 1
+    ;;
+esac
+'''
+
+
+class FakeSf:
+    def __enter__(self):
+        self._directory = tempfile.mkdtemp(prefix="omni-limits-fake-sf-")
+        self.log_path = Path(self._directory) / "commands.log"
+        sf_path = Path(self._directory) / "sf"
+        sf_path.write_text(_FAKE_SF)
+        sf_path.chmod(0o755)
+        return self
+
+    def run(self, args: list[str], **values):
+        env = dict(os.environ)
+        env["PATH"] = self._directory + os.pathsep + env.get("PATH", "")
+        env["FAKE_SF_LOG"] = str(self.log_path)
+        for key, value in values.items():
+            env[key] = json.dumps(value) if key == "FAKE_QUERY_BODY" and not isinstance(value, str) else str(value)
+        process = subprocess.run(
+            ["bash", str(SCRIPT), *args],
+            capture_output=True,
+            text=True,
+            env=env,
+            cwd=str(SKILLS_ROOT),
+        )
+        commands = self.log_path.read_text() if self.log_path.exists() else ""
+        return process.returncode, process.stdout + process.stderr, commands
+
+    def __exit__(self, *_):
+        shutil.rmtree(self._directory, ignore_errors=True)
+
+
+def last_json(output: str) -> dict:
+    decoder = json.JSONDecoder()
+    parsed = None
+    position = 0
+    while position < len(output):
+        if output[position] == "{":
+            try:
+                candidate, end = decoder.raw_decode(output, position)
+                parsed = candidate
+                position = end
+                continue
+            except json.JSONDecodeError:
+                pass
+        position += 1
+    assert parsed is not None, f"No JSON object found in output:\n{output}"
+    return parsed

package/skills/service-omni-channel-limits-analyze/scripts/tests/test_limits_analyze_contracts.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import unittest
+
+from _bootstrap import FakeSf, last_json
+
+
+class InputContractTests(unittest.TestCase):
+    def test_missing_org_is_rejected(self):
+        with FakeSf() as fake:
+            return_code, output, commands = fake.run([])
+        self.assertEqual(return_code, 1, output)
+        self.assertIn("Usage", output)
+        self.assertEqual(commands, "")
+
+    def test_invalid_routing_model_is_blocked_before_query(self):
+        with FakeSf() as fake:
+            return_code, output, commands = fake.run(["org", "--routing-model", "future"])
+        self.assertEqual(return_code, 1, output)
+        self.assertEqual(last_json(output)["status"], "blocked")
+        self.assertEqual(commands, "")
+
+    def test_invalid_maximum_is_blocked_before_query(self):
+        with FakeSf() as fake:
+            return_code, output, commands = fake.run(["org", "--max-psrs", "0"])
+        self.assertEqual(return_code, 1, output)
+        self.assertIn("1 through 1000000", last_json(output)["blocking_issue"])
+        self.assertEqual(commands, "")
+
+    def test_unauthenticated_org_is_blocked(self):
+        with FakeSf() as fake:
+            return_code, output, commands = fake.run(["org"], FAKE_AUTH="fail")
+        self.assertEqual(return_code, 1, output)
+        self.assertEqual(last_json(output)["status"], "blocked")
+        self.assertEqual(commands, "")
+
+
+class LimitsContractTests(unittest.TestCase):
+    def test_enhanced_report_uses_live_count_and_reference_default(self):
+        with FakeSf() as fake:
+            return_code, output, commands = fake.run(["org"])
+        self.assertEqual(return_code, 0, output)
+        result = last_json(output)
+        current = result["metrics"]["current_pending_service_routings"]
+        hourly = result["metrics"]["pending_service_routing_rate_per_hour"]
+        self.assertEqual(current["used"], 2)
+        self.assertEqual(current["limit"], 300000)
+        self.assertEqual(current["limit_source"], "reference_default")
+        self.assertTrue(current["usage_is_approximate"])
+        self.assertIsNone(hourly["used"])
+        self.assertIsNone(hourly["usage_percent"])
+        self.assertIn("SELECT COUNT() FROM PendingServiceRouting", commands)
+        self.assertNotRegex(commands, r"\b(create|update|delete|deploy)\b")
+
+    def test_legacy_model_selects_legacy_reference_default(self):
+        with FakeSf() as fake:
+            return_code, output, _ = fake.run(["org", "--routing-model", "legacy"])
+        self.assertEqual(return_code, 0, output)
+        result = last_json(output)
+        self.assertEqual(result["routing_model"], "legacy")
+        self.assertEqual(result["metrics"]["current_pending_service_routings"]["limit"], 200000)
+
+    def test_admin_maximum_is_labeled_and_not_api_verified(self):
+        with FakeSf() as fake:
+            return_code, output, _ = fake.run(["org", "--max-psrs", "500000"])
+        self.assertEqual(return_code, 0, output)
+        metric = last_json(output)["metrics"]["current_pending_service_routings"]
+        self.assertEqual(metric["limit"], 500000)
+        self.assertEqual(metric["limit_source"], "admin_supplied")
+        self.assertFalse(metric["limit_verified_by_api"])
+
+    def test_aggregate_expr0_shape_is_supported(self):
+        body = {"status": 0, "result": {"totalSize": 1, "records": [{"expr0": 17}]}}
+        with FakeSf() as fake:
+            return_code, output, _ = fake.run(["org"], FAKE_QUERY_BODY=body)
+        self.assertEqual(return_code, 0, output)
+        used = last_json(output)["metrics"]["current_pending_service_routings"]["used"]
+        self.assertEqual(used, 17)
+
+    def test_unavailable_object_is_blocked_not_zero(self):
+        body = {"status": 1, "name": "INVALID_TYPE", "message": "sObject type is not supported"}
+        with FakeSf() as fake:
+            return_code, output, _ = fake.run(["org"], FAKE_QUERY_STATUS="fail", FAKE_QUERY_BODY=body)
+        self.assertEqual(return_code, 1, output)
+        result = last_json(output)
+        self.assertEqual(result["status"], "blocked")
+        self.assertIsNone(result["metrics"])
+        self.assertIn("usage was not treated as zero", result["blocking_issue"])
+
+    def test_malformed_success_is_blocked(self):
+        with FakeSf() as fake:
+            return_code, output, _ = fake.run(["org"], FAKE_QUERY_BODY={"status": 0, "result": {}})
+        self.assertEqual(return_code, 1, output)
+        self.assertEqual(last_json(output)["status"], "blocked")
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

package/skills/service-omni-channel-setup-coordinate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: service-omni-channel-setup-coordinate
-description: "Use to stand up Omni-Channel setup headlessly on Salesforce: base settings, agent users, service channels, routing configs, queues (create and align) and members, presence statuses, permission assignments, the classic Omni Supervisor config plus its action/tab surface, and — for Case and VoiceCall — the record-triggered routing flow. Supports Case, Incident, MessagingSession, and VoiceCall targets; reuses existing records and creates what is missing. Opt-in extras: presence user config, Omni sidebar, skills-based routing, and field-based WorkSkillRouting; also reports (read-only) whether the org is on the classic supervisor surface or Command Center V2. Triggers: set up Omni-Channel, configure Omni routing, provision Omni agents or supervisors, configure Case/Incident/Messaging/Voice routing. Do not use for Agentforce agents or bots, a single existing Omni field change, bare metadata deployment (use platform-metadata-deploy), or to enable Command Center V2 (not writable via the Metadata API)."
+description: "Use to stand up Omni-Channel headlessly: base settings, users, service channels, routing configs, queues and members, presence statuses, permissions, supervisor configuration, and Case or VoiceCall routing flows. Reuses existing records and creates missing ones. Optional stages cover Command Center V2 on supported releases, agent experience, and skills-based routing. TRIGGER when: set up Omni-Channel, configure Omni routing, provision Omni agents, provision Omni supervisors, or configure Case, Incident, MessagingSession, or VoiceCall routing. Do not use for Agentforce bots, one existing field change, or bare metadata deployment."
 allowed-tools: Bash Read Write Edit Glob Grep AskUserQuestion TodoWrite
 metadata:
   version: "1.0"
@@ -11,6 +11,7 @@ metadata:
     - "service-agentforce-human-escalation-configure"
     - "service-omni-agent-users-create"
     - "service-omni-base-settings-configure"
+    - "service-omni-channel-inventory-analyze"
     - "service-omni-command-center-analyze"
     - "service-omni-permission-set-assign"
     - "service-omni-presence-status-deploy"
@@ -79,20 +80,22 @@ bash scripts/integration-driver.sh --run  <org-alias> [agent_count] [routing_tar
 - `Incident` targets require the Incident Management feature enabled; `MessagingSession` requires Enhanced Messaging; `VoiceCall` requires Service Cloud Voice. The readiness check hard-fails with a click-path when a requested target sObject is absent.
 - **Production guardrail:** `safe_to_write` is `true` iff any of `IsSandbox = true`, `TrialExpirationDate != null`, or `OrganizationType IN ('Developer Edition', 'Base Edition')`. The run hard-refuses when it is false. CDOs return `IsSandbox=false` with a non-null `TrialExpirationDate` and must be permitted, so `IsSandbox` alone is never the guard.
 
-Readiness check (silent, mandatory, before any leaf runs):
+Readiness check (mandatory, before any write leaf runs):
 
 1. `sf org display` → confirm the org alias is authenticated; refuse (exit 1) if not.
 2. `Organization` (`IsSandbox`, `TrialExpirationDate`, `OrganizationType`) → compute `safe_to_write`; refuse (exit 1) if false.
-3. Preflight entity availability → for each **non-`Case`** routing target, confirm the sObject exists via `EntityDefinition`; a missing target hard-fails with a feature-enablement click-path (exit 2). `Case` is assumed present and skipped.
+3. `service-omni-channel-inventory-analyze` → capture the complete channel/routing baseline through the approved read-only aggregate operation; a blocked inventory prevents writes because the coordinator cannot safely establish the starting state.
+4. Preflight entity availability → for each **non-`Case`** routing target, confirm the sObject exists via `EntityDefinition`; a missing target hard-fails with a feature-enablement click-path (exit 2). `Case` is assumed present and skipped.
 
 Omni-Channel base-settings enablement is not a separate upfront probe — it is detected by the base-settings leaf (step 1), and downstream Omni-dependent leaves are deferred as pending in `--plan` until it is on. The driver does not pre-check `UserLicense` headroom or `ServicePresenceStatus`/`QueueRoutingConfig` availability in this readiness pass.
 
 ## Skills this coordinates
 
-The coordinator delegates every write to a leaf skill. sObject-specific leaves (3, 5, 6, 6c, 7) loop once per routing target; the rest run once. For SkillsBased routing, steps 6a and 6b complete before any trigger flow is activated. Step 10a (`command-center-analyze`) is a read-only advisory and always runs. Step 11a (`supervisor-surface-deploy`) always runs after the supervisor config succeeds. Leaves 12–13 are the opt-in rep-experience stages (`OMNI_REP_EXPERIENCE=1`).
+The coordinator delegates every write to a leaf skill. sObject-specific leaves (3, 5, 6, 6c, 7) loop once per routing target; the rest run once. For SkillsBased routing, steps 6a and 6b complete before any trigger flow is activated. Step 10a (`command-center-configure`) is opt-in through `OMNI_COMMAND_CENTER_V2=1`; step 10b (`command-center-analyze`) is a read-only advisory and always runs. Step 11a (`supervisor-surface-deploy`) always runs after the supervisor config succeeds. Leaves 12–13 are the opt-in rep-experience stages (`OMNI_REP_EXPERIENCE=1`).
 
 | # | Child skill | Role |
 |---|---|---|
+| 0 | `service-omni-channel-inventory-analyze` | Capture the read-only cross-channel and routing baseline before any writes |
 | 1 | `service-omni-base-settings-configure` | Deploy `Settings:OmniChannel` (5 toggles) |
 | 2 | `service-omni-agent-users-create` | Provision the requested agent users |
 | 3 | `service-omni-service-channel-configure` | Reuse the standard `ServiceChannel` for the target sObject, or deploy the canonical XML |
@@ -106,7 +109,8 @@ The coordinator delegates every write to a leaf skill. sObject-specific leaves (
 | 8 | `service-omni-permission-set-assign` | Assign the `Omni_Agent` PermissionSet to agent users; self-heals the bundled metadata when absent (run mode only) |
 | 9 | `service-omni-supervisor-users-create` | Provision supervisor users |
 | 10 | `service-omni-supervisor-permset-assign` | Assign the standard `ContactCenterSupervisor` PermissionSet to supervisor users |
-| 10a | `service-omni-command-center-analyze` | **Read-only advisory** — report whether the org is on the classic supervisor surface or Command Center V2; never writes, never hard-blocks |
+| 10a | `service-omni-command-center-configure` | *(opt-in)* Enable Command Center V2 through preserved `OmniChannel.settings` and verify its seeded page and tab |
+| 10b | `service-omni-command-center-analyze` | **Read-only advisory** — report whether the org is on the classic supervisor surface or Command Center V2; never writes, never hard-blocks |
 | 11 | `service-omni-supervisor-config-deploy` | Deploy `OmniSupervisorConfig` binding supervisor users to the queues discovered in step 5 |
 | 11a | `service-omni-supervisor-surface-deploy` | Populate the supervisor **action + tab surface** (`OmniSupervisorConfigAction` / `OmniSupervisorConfigTab`) on the config from step 11 |
 | 12 | `service-omni-presence-user-config-deploy` | *(opt-in)* Deploy `PresenceUserConfig` + `PresenceDeclineReason` (decline + ACW) and assign the provisioned agents |
@@ -119,7 +123,7 @@ The coordinator delegates every write to a leaf skill. sObject-specific leaves (
 
 **Ordering and gating.** Leaves run in dependency order. Base settings are a hard prerequisite for every write below. For SkillsBased routing, agent `SkillUser` bindings (6a) and the `WorkSkillRouting` rule (6b) must succeed before the routing-flow leaf (6c) can activate the trigger. The flow also requires the queue (5) and its members (6), and it round-trips `FlowDefinitionView.ActiveVersionId` to prove the flow is Active. A required runtime proof does not pass merely because a PSR exists: SkillsBased requires at least one `SkillRequirement` on that PSR.
 
-**Supervisor path.** Supervisor users (9) use the same Anonymous Apex `System.setPassword` model as agent users. Because a password literal can be captured in an `ApexLog` when a debug TraceFlag is active, both user-create leaves fail closed *before* the first `System.setPassword`: they prove via a SOQL-filtered Tooling API query (`ExpirationDate > now`) that no active TraceFlag exists for the running user, and if that cannot be positively proven they set no password at all (users left ACTIVE and `reset_required`, with a `security_warning`). They never delete logs, so unrelated audit logs are untouched. The supervisor permset leaf (10) assigns the standard `ContactCenterSupervisor` — never the custom `Omni_Supervisor`, whose license-gated permissions fail assignment — and a contract test asserts this wiring. After the supervisor permset, a read-only Command Center analysis (10a) reports the org's supervisor surface (classic vs Command Center V2); it never writes and never hard-blocks (ambiguous detection is yellow, a clean read green). Once the config lands (11), the surface leaf (11a) inserts the standard action + tab companions (`OmniSupervisorConfigAction` / `OmniSupervisorConfigTab`) against the config's Id — plain Data API rows, so no metadata-file redeploy — and is idempotent (only missing types are inserted). It runs only after the config succeeds; a skipped or failed config skips the surface with a dependency note.
+**Supervisor path.** Supervisor users (9) use the same Anonymous Apex `System.setPassword` model as agent users. Because a password literal can be captured in an `ApexLog` when a debug TraceFlag is active, both user-create leaves fail closed *before* the first `System.setPassword`: they prove via a SOQL-filtered Tooling API query (`ExpirationDate > now`) that no active TraceFlag exists for the running user, and if that cannot be positively proven they set no password at all (users left ACTIVE and `reset_required`, with a `security_warning`). They never delete logs, so unrelated audit logs are untouched. The supervisor permset leaf (10) assigns the standard `ContactCenterSupervisor` — never the custom `Omni_Supervisor`, whose license-gated permissions fail assignment — and a contract test asserts this wiring. With `OMNI_COMMAND_CENTER_V2=1`, the coordinator enables and verifies the V2 org preference through `service-omni-command-center-configure`; optional `OMNI_COMMAND_CENTER_*` booleans select its subordinate controls. A read-only Command Center analysis then reports the resulting supervisor surface and never hard-blocks (ambiguous detection is yellow, a clean read green). Once the classic config lands (11), the surface leaf (11a) inserts the standard action + tab companions (`OmniSupervisorConfigAction` / `OmniSupervisorConfigTab`) against the config's Id — plain Data API rows, so no metadata-file redeploy — and is idempotent (only missing types are inserted). It runs only after the config succeeds; a skipped or failed config skips the surface with a dependency note.
 
 **Optional rep-experience stages.** With `OMNI_REP_EXPERIENCE=1`, presence user config (12) deploys a validator-safe `PresenceUserConfig` with its decline reason and assigns every resolved agent username, including reused users. Sidebar (13) pins the Omni utility region on `OMNI_CONSOLE_APP`, or auto-detects a single console app. SkillsBased routing is not a cosmetic rep-experience stage: when requested, its SkillUser and WorkSkillRouting prerequisites run before flow activation.
 
@@ -142,23 +146,11 @@ Report content rules:
 ## Limitations
 
 - Routing-flow deploy covers `Case` and `VoiceCall` only.
-- Classic `OmniSupervisorConfig` (including its action + tab surface) only. Command Center V2 (Enhanced Omni-Channel) is reported by the read-only analysis step but not enabled — the org preference is not writable via the Metadata API. The surface leaf populates only the reference-free standard action/tab types; custom-action, FlexiPage, AWS-dashboard, and AI-agent surfaces need an external reference and must be set up in Setup.
+- Classic `OmniSupervisorConfig`, including its standard action and tab surface, is supported. Command Center V2 is an explicit opt-in (`OMNI_COMMAND_CENTER_V2=1`) and runs only when the org's Metadata API exposes the V2 settings; otherwise the configure leaf fails closed. Custom actions, FlexiPages, AWS dashboards, and AI-agent surfaces still need external references and separate setup.
 - The rep-experience stages (presence user config, decline reasons, sidebar) run only with `OMNI_REP_EXPERIENCE=1`. SkillsBased routing is selected explicitly or inferred from a complete `OMNI_WSR_*` mapping and runs independently of that flag.
 - Teardown is **plan-only**: `--run` emits `deploy_ids.json` (a provenance manifest) and a dry-run `teardown.sh` that prints the reverse-order removal/restore plan, but does not execute destructive changes. Automated reversal is deliberately deferred until every leaf emits a normalized provenance block and the reversal is validated live — metadata-deployed components need destructiveChanges deploys and adopted records must never be deleted. Reversal today is a manual operator task guided by the plan and the per-skill artifacts.
 
-### Use-case coverage (current)
-
-| Use case | Status | What is / isn't headless |
-| --- | --- | --- |
-| Case routing | Ready | Full create-and-bind thread (queue + QRC + members + routing flow), idempotent; runtime `PendingServiceRouting` proof optional. |
-| VoiceCall / AFCC routing | Conditional | QRC + queue + members + routing flow are deployable, but require a **provisioned Amazon/AFCC contact center** and a live Voice runtime to prove end-to-end. Contact-center provisioning is the caller's responsibility. |
-| Open CTI → AFCC migration | Partial | The coordinator creates the Omni routing resources; it does not provision or migrate the contact center itself. |
-| Incident routing | Partial | Service channel + presence are supported; the coordinator **verifies/adopts** Incident routing but does not create a missing queue/QRC/flow for it. |
-| Generic MessagingSession routing | Partial | Service channel + presence supported; full create-and-bind is delegated to `service-agentforce-human-escalation-configure`, not run generically here. |
-| Classic Omni Supervisor | Ready | Users, permissions, config, queues/users, and the action/tab surface companions are all implemented. |
-| Command Center V2 | Detection only | The read-only analysis step reports classic vs V2; the org preference `CommandCenterForServiceV2` is **not writable via the Metadata API** (tracked: W-23827287) and must be enabled in Setup. |
-| Supervisor monitoring OrgValues | Not implemented | `OmniSuperConvMonitor`, `OmniSuperAgentSneakpeek`, `OmniSuperClientSneakpeek`, `OmniSuperWhisper`, `OmniSuperAdminSkillQueue` are OrgValues with no proven supported external write API. |
-| Omni Inbox | Not implemented | The sidebar leaf pins the Omni sidebar (`isOmniPinnedViewEnabled`); it does not create or configure Omni Inbox, a console app, or utility items. |
+Detailed coverage and known headless gaps are maintained in `references/gap-catalog.md`. In short, Case routing is fully coordinated; VoiceCall needs a provisioned voice runtime; Incident and generic MessagingSession routing are adopted rather than created; and Omni Inbox or external supervisor surfaces remain outside this workflow.
 
 ## References
 

package/skills/service-omni-channel-setup-coordinate/scripts/integration-driver.sh

@@ -68,6 +68,25 @@ SUPERVISOR_COUNT="${4:-1}"
 AGENT_PROFILE="${OMNI_AGENT_PROFILE:-}"
 SUPERVISOR_PROFILE="${OMNI_SUPERVISOR_PROFILE:-}"
 SUPERVISOR_CONFIG_DN="${OMNI_SUPERVISOR_CONFIG_DEVELOPER_NAME:-Omni_Supervisor}"
+COMMAND_CENTER_V2="${OMNI_COMMAND_CENTER_V2:-0}"
+
+case "$COMMAND_CENTER_V2" in
+  0|1) ;;
+  *) echo "{\"error\":\"Invalid OMNI_COMMAND_CENTER_V2 '$COMMAND_CENTER_V2'. Supported: 0 or 1.\"}" >&2; exit 2 ;;
+esac
+
+for command_center_setting in \
+  OMNI_COMMAND_CENTER_CONVERSATION_MONITORING \
+  OMNI_COMMAND_CENTER_AGENT_SNEAK_PEEK \
+  OMNI_COMMAND_CENTER_CUSTOMER_SNEAK_PEEK \
+  OMNI_COMMAND_CENTER_WHISPER_MESSAGING \
+  OMNI_COMMAND_CENTER_QUEUES_AND_SKILLS; do
+  command_center_value="${!command_center_setting:-}"
+  if [ -n "$command_center_value" ] && [ "$command_center_value" != "true" ] && [ "$command_center_value" != "false" ]; then
+    echo "{\"error\":\"Invalid $command_center_setting '$command_center_value'. Supported: true or false.\"}" >&2
+    exit 2
+  fi
+done
 
 # A complete WorkSkillRouting mapping is an unambiguous SBR request. Infer SkillsBased so callers do
 # not need a hidden second switch; an explicit OMNI_ROUTING_TYPE still wins.
@@ -544,7 +563,7 @@ run_skill() {
   # configured/bound/assigned/ok/success/skipped.
   local color
   case "$status" in
-    reused|updated|created|deployed|configured|bound|assigned|ok|success|skipped)
+    analyzed|reused|updated|created|deployed|configured|bound|assigned|ok|success|skipped)
       color="green"
       ;;
     action_needed|partial|unsupported_v1|not_evaluated)
@@ -611,6 +630,16 @@ run_skill() {
   return 0
 }
 
+# ---- Read-only cross-channel baseline ----
+# A blocked inventory means the coordinator cannot establish an authoritative starting state, so no
+# write leaf is allowed to run.
+run_skill "service-omni-channel-inventory-analyze" \
+  "service-omni-channel-inventory-analyze" \
+  "Omni channel and routing inventory (read-only preflight)" \
+  '.status' \
+  analyze.sh "$ORG" \
+  || exit 1
+
 # ---- Base settings ----
 # Plan detects; run deploys the 5 OmniChannelSettings toggles + re-verifies. Hard prerequisite for
 # every write skill below (INVALID_TYPE when Omni is off), so a red here fails fast.
@@ -1247,11 +1276,32 @@ else
     || true
 fi
 
+# ---- Command Center V2 configuration (explicit opt-in) ----
+if [ "$COMMAND_CENTER_V2" = "1" ]; then
+  if [ "$MODE" = "run" ]; then
+    COMMAND_CENTER_ARGS=(run "$ORG" --apply)
+  else
+    COMMAND_CENTER_ARGS=(plan "$ORG")
+  fi
+
+  [ -z "${OMNI_COMMAND_CENTER_CONVERSATION_MONITORING:-}" ] || COMMAND_CENTER_ARGS+=(--conversation-monitoring "$OMNI_COMMAND_CENTER_CONVERSATION_MONITORING")
+  [ -z "${OMNI_COMMAND_CENTER_AGENT_SNEAK_PEEK:-}" ] || COMMAND_CENTER_ARGS+=(--agent-sneak-peek "$OMNI_COMMAND_CENTER_AGENT_SNEAK_PEEK")
+  [ -z "${OMNI_COMMAND_CENTER_CUSTOMER_SNEAK_PEEK:-}" ] || COMMAND_CENTER_ARGS+=(--customer-sneak-peek "$OMNI_COMMAND_CENTER_CUSTOMER_SNEAK_PEEK")
+  [ -z "${OMNI_COMMAND_CENTER_WHISPER_MESSAGING:-}" ] || COMMAND_CENTER_ARGS+=(--whisper-messaging "$OMNI_COMMAND_CENTER_WHISPER_MESSAGING")
+  [ -z "${OMNI_COMMAND_CENTER_QUEUES_AND_SKILLS:-}" ] || COMMAND_CENTER_ARGS+=(--queues-and-skills "$OMNI_COMMAND_CENTER_QUEUES_AND_SKILLS")
+
+  run_skill "service-omni-command-center-configure" \
+    "service-omni-command-center-configure" \
+    "Command Center for Service V2 (opt-in Metadata API configuration)" \
+    '.status' \
+    configure-and-report.sh "${COMMAND_CENTER_ARGS[@]}" \
+    || true
+fi
+
 # ---- Command Center surface analysis (read-only advisory) ----
-# Reports whether the org is on the classic Omni Supervisor surface or Command Center V2 (Enhanced
-# Omni-Channel). Advisory only: this coordinator configures the classic surface; V2 enablement is an
-# org-preference flip outside the Metadata API. It never writes, so it runs identically in plan and
-# run and never hard-blocks - ambiguous detection surfaces as yellow, a clean read as green.
+# Reports whether the org is on the classic Omni Supervisor surface or Command Center V2 after any
+# requested V2 configuration. It never writes and never hard-blocks: ambiguous detection surfaces
+# as yellow, while a clean read is green.
 run_skill "service-omni-command-center-analyze" \
   "service-omni-command-center-analyze" \
   "Command Center surface analysis (classic vs V2, read-only)" \

package/skills/service-omni-channel-setup-coordinate/scripts/tests/test_omni_contracts.py

@@ -586,6 +586,26 @@ class SkillsBasedRoutingFlowTests(unittest.TestCase):
             return _run(_FLOW_SCRIPT, args, path_prefix=fake_dir, extra_env=merged)
 
 
+class CoordinatorInventoryPreflightTests(unittest.TestCase):
+    """The authoritative cross-channel inventory must run before the first write leaf."""
+
+    DRIVER = SKILLS_ROOT / "service-omni-channel-setup-coordinate" / "scripts" / "integration-driver.sh"
+
+    def test_inventory_runs_before_base_settings(self):
+        source = self.DRIVER.read_text()
+        inventory_index = source.index('run_skill "service-omni-channel-inventory-analyze"')
+        base_index = source.index('run_skill "service-omni-base-settings-configure"')
+        self.assertLess(inventory_index, base_index)
+
+    def test_inventory_failure_stops_the_driver(self):
+        source = self.DRIVER.read_text()
+        invocation = re.search(
+            r'run_skill "service-omni-channel-inventory-analyze"[\s\S]+?\|\| exit 1',
+            source,
+        )
+        self.assertIsNotNone(invocation, "blocked inventory must stop the coordinator before writes")
+
+
 class VoiceMembershipContractTests(unittest.TestCase):
     """(7) Explicit real-agent membership contract for service-omni-queue-members-assign."""
 
@@ -765,6 +785,24 @@ class CoordinatorSupervisorSurfaceTests(unittest.TestCase):
             self.src, r'(?m)^run_skill "service-omni-command-center-analyze"',
             "command-center-analyze must be invoked top-level, outside the OMNI_REP_EXPERIENCE gate")
 
+    def test_command_center_v2_configuration_is_explicit_and_precedes_analysis(self):
+        self.assertIn('COMMAND_CENTER_V2="${OMNI_COMMAND_CENTER_V2:-0}"', self.src)
+        self.assertIn('run_skill "service-omni-command-center-configure"', self.src)
+        configure_at = self.src.index('run_skill "service-omni-command-center-configure"')
+        analyze_at = self.src.index('run_skill "service-omni-command-center-analyze"')
+        self.assertLess(configure_at, analyze_at)
+        self.assertIn('COMMAND_CENTER_ARGS=(run "$ORG" --apply)', self.src)
+
+    def test_command_center_control_inputs_are_forwarded(self):
+        for option in (
+            "--conversation-monitoring",
+            "--agent-sneak-peek",
+            "--customer-sneak-peek",
+            "--whisper-messaging",
+            "--queues-and-skills",
+        ):
+            self.assertIn(option, self.src)
+
     def test_supervisor_surface_invoked_after_config(self):
         self.assertIn("service-omni-supervisor-surface-deploy", self.src,
                       "coordinator never invokes supervisor-surface-deploy")

package/skills/service-omni-command-center-analyze/SKILL.md

@@ -60,7 +60,7 @@ bash scripts/analyze.sh <org-alias> [supervisor_username_or_id]
 | `v2_ready` | Capability + seed present (and supervisor has permission, if checked) | verify only (coordinator proceeds to V2 verification) |
 | `v2_permission_missing` | V2 enabled but the named supervisor lacks `CommandCenterForServiceUser` | Manual — assign `CommandCenterForServiceUser` (headless-capable via PermissionSet; packaging pending) |
 | `v2_seed_incomplete` | Capability present but the FlexiPage/tab provisioning is inconsistent | Manual — re-check in Setup → Omni-Channel → Supervisor Settings (no supported public write API) |
-| `v2_available_not_enabled` | Org supports V2 but the preference is off | Manual — enable in Setup → Omni-Channel → Supervisor Settings (no supported Metadata/Tooling write API) |
+| `v2_available_not_enabled` | Org supports V2 but the preference is off | `service-omni-command-center-configure` when the W-24039822 Metadata API contract is available; otherwise enable manually |
 | `legacy_selected` | V2 capability absent | `service-omni-supervisor-config-deploy` |
 | `ambiguous` | A required signal could not be read through a supported API | none — **blocks**, do not guess |
 
@@ -72,7 +72,7 @@ A single JSON object: `status` (`detected` | `blocked`), `state` (one of the six
 
 ## Limitations
 
-- The `CommandCenterForServiceV2` org preference has no supported public read; its state is **inferred** from the seeded FlexiPage (the platform seeds on the ON-flip). This is called out in `signals` and is why a bare capability-without-seed reads as `v2_available_not_enabled`.
+- The analyzer keeps using the seeded FlexiPage as its cross-release read signal. On releases containing W-24039822, `service-omni-command-center-configure` can write and re-read the preference through `Settings:OmniChannel`.
 - The release gater cannot be read directly; capability is inferred from the presence of the user-permission column on the org schema.
 - Tab detection is best-effort; when the tab query cannot run, `v2_tab_present` is `"unknown"` and state is derived from the remaining signals.
 - Read-only: it never enables V2, seeds pages, assigns permissions, or deploys config.

package/skills/service-omni-command-center-analyze/scripts/analyze.sh

@@ -142,8 +142,8 @@ else
     REC_SKILL="null"
   else
     STATE="v2_available_not_enabled"
-    REC_ACTION="Org supports V2 but the CommandCenterForServiceV2 preference is off (no seeded page). Enable it manually in Setup → Omni-Channel → Supervisor Settings; there is no supported Metadata/Tooling write API for this preference."
-    REC_SKILL="null"
+    REC_ACTION="Org supports V2 but the CommandCenterForServiceV2 preference is off (no seeded page). Use service-omni-command-center-configure when the W-24039822 Metadata API contract is available; otherwise enable it manually in Setup → Omni-Channel → Supervisor Settings."
+    REC_SKILL='"service-omni-command-center-configure"'
   fi
 fi
 
@@ -153,7 +153,7 @@ case "$STATE" in
   v2_permission_missing)
     MANUAL_ACTIONS=$(jq -n '[{id:"ASSIGN_V2_PERM",title:"Assign the CommandCenterForServiceUser permission to the supervisor (headless-capable via PermissionSet; packaging pending)",target_skill:null}]') ;;
   v2_available_not_enabled|v2_seed_incomplete)
-    MANUAL_ACTIONS=$(jq -n '[{id:"ENABLE_V2_PREF",title:"Enable Command Center for Service V2 in Setup → Omni-Channel → Supervisor Settings (no supported public write API; manual)",target_skill:null}]') ;;
+    MANUAL_ACTIONS=$(jq -n '[{id:"ENABLE_V2_PREF",title:"Enable Command Center for Service V2 with service-omni-command-center-configure when the W-24039822 API field is available; otherwise use Setup → Omni-Channel → Supervisor Settings",target_skill:"service-omni-command-center-configure"}]') ;;
 esac
 
 # Emit

package/skills/dx-org-manage/examples/snapshots/error_output.json

@@ -1,9 +0,0 @@
-{
-  "status": 1,
-  "name": "DuplicateValue",
-  "message": "A snapshot named 'MySnapshot' already exists in this Dev Hub. Use a different, unique name.",
-  "exitCode": 1,
-  "commandName": "SnapshotCreate",
-  "stack": "DuplicateValue: A snapshot named 'MySnapshot' already exists in this Dev Hub...",
-  "warnings": []
-}