@salesforce/afv-skills 1.47.0 → 1.49.0

package/skills/service-omni-agent-work-sharing-configure/scripts/configure-and-report.sh

@@ -0,0 +1,186 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+ORG="${1:-}"
+MODE="run"
+CONFIRMED="false"
+
+if [ "$#" -gt 0 ]; then
+  shift
+fi
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --plan) MODE="plan" ;;
+    --confirm-org-wide-visibility) CONFIRMED="true" ;;
+    *)
+      echo '{"status":"blocked","blocking_issue":"Usage: configure-and-report.sh <org-alias> [--plan] [--confirm-org-wide-visibility]"}'
+      exit 1
+      ;;
+  esac
+  shift
+done
+
+if [ -z "$ORG" ]; then
+  echo '{"status":"blocked","blocking_issue":"An authenticated org alias is required."}'
+  exit 1
+fi
+
+WORK_DIR=$(mktemp -d "${TMPDIR:-/tmp}/agentwork-sharing.XXXXXX")
+trap 'rm -rf "$WORK_DIR"' EXIT
+
+emit_result() {
+  local status="$1" previous_model="$2" current_model="$3" external_model="$4"
+  local changed="$5" dry_run="$6" deploy_id="$7" blocking_issue="$8"
+  jq -n \
+    --arg status "$status" \
+    --arg previous "$previous_model" \
+    --arg current "$current_model" \
+    --arg external "$external_model" \
+    --arg changed "$changed" \
+    --arg dry_run "$dry_run" \
+    --arg deploy_id "$deploy_id" \
+    --arg blocking_issue "$blocking_issue" \
+    '{
+      skill: "service-omni-agent-work-sharing-configure",
+      status: $status,
+      previous_sharing_model: (if $previous == "" then null else $previous end),
+      sharing_model: (if $current == "" then null else $current end),
+      external_sharing_model: (if $external == "" then null else $external end),
+      changed: ($changed == "true"),
+      dry_run: ($dry_run == "true"),
+      deploy_id: (if $deploy_id == "" then null else $deploy_id end),
+      blocking_issue: (if $blocking_issue == "" then null else $blocking_issue end)
+    }'
+}
+
+xml_value() {
+  local tag="$1" file="$2"
+  tr -d '\n\r' < "$file" | sed -n "s:.*<$tag>\([^<]*\)</$tag>.*:\1:p"
+}
+
+retrieve_agent_work() {
+  local destination="$1" result object_file
+  mkdir -p "$destination"
+  if ! result=$(sf project retrieve start \
+      --metadata "CustomObject:AgentWork" \
+      --target-org "$ORG" \
+      --target-metadata-dir "$destination" \
+      --unzip \
+      --json 2>&1); then
+    return 1
+  fi
+  if [ "$(jq -r '.status // 1' <<<"$result" 2>/dev/null)" != "0" ]; then
+    return 1
+  fi
+  object_file=$(find "$destination" -type f -name 'AgentWork.object' -print -quit)
+  if [ -z "$object_file" ]; then
+    return 1
+  fi
+  printf '%s' "$object_file"
+}
+
+dry_run="false"
+if [ "$MODE" = "plan" ]; then
+  dry_run="true"
+fi
+
+org_result=$(sf data query \
+  --query "SELECT IsSandbox, TrialExpirationDate, OrganizationType FROM Organization LIMIT 1" \
+  --target-org "$ORG" \
+  --json 2>&1) || {
+    emit_result "blocked" "" "" "" false "$dry_run" "" \
+      "Unable to classify the target org; refusing an org-wide sharing change."
+    exit 1
+  }
+
+is_sandbox=$(jq -r '.result.records[0].IsSandbox // false' <<<"$org_result" 2>/dev/null)
+trial_expiration=$(jq -r '.result.records[0].TrialExpirationDate // empty' <<<"$org_result" 2>/dev/null)
+organization_type=$(jq -r '.result.records[0].OrganizationType // empty' <<<"$org_result" 2>/dev/null)
+if [ "$MODE" = "run" ] \
+    && [ "$is_sandbox" != "true" ] \
+    && [ -z "$trial_expiration" ] \
+    && [ "$organization_type" != "Developer Edition" ] \
+    && [ "$organization_type" != "Base Edition" ]; then
+  emit_result "blocked" "" "" "" false false "" \
+    "Production customer org detected; org-wide AgentWork sharing changes are refused."
+  exit 1
+fi
+
+if ! object_file=$(retrieve_agent_work "$WORK_DIR/before"); then
+  emit_result "blocked" "" "" "" false "$dry_run" "" \
+    "Unable to retrieve CustomObject:AgentWork through the Metadata API."
+  exit 1
+fi
+
+previous_model=$(xml_value sharingModel "$object_file")
+external_model=$(xml_value externalSharingModel "$object_file")
+if [[ ! "$previous_model" =~ ^(Private|Read|ReadWrite)$ ]] || [[ ! "$external_model" =~ ^(Private|Read|ReadWrite)$ ]]; then
+  emit_result "blocked" "$previous_model" "$previous_model" "$external_model" false "$dry_run" "" \
+    "AgentWork sharing metadata was incomplete or used an unsupported sharing model."
+  exit 1
+fi
+
+if [ "$previous_model" = "Read" ] || [ "$previous_model" = "ReadWrite" ]; then
+  emit_result "reused" "$previous_model" "$previous_model" "$external_model" false "$dry_run" "" ""
+  exit 0
+fi
+
+if [ "$MODE" = "plan" ]; then
+  emit_result "action_needed" "$previous_model" "Read" "$external_model" false true "" ""
+  exit 2
+fi
+
+if [ "$CONFIRMED" != "true" ]; then
+  emit_result "blocked" "$previous_model" "$previous_model" "$external_model" false false "" \
+    "Changing AgentWork from Private to Read expands org-wide internal visibility. Re-run with --confirm-org-wide-visibility after reviewing the blast radius."
+  exit 1
+fi
+
+source_root="$WORK_DIR/source"
+mkdir -p "$source_root/force-app/main/default/objects/AgentWork"
+cat > "$source_root/sfdx-project.json" <<'JSON'
+{"packageDirectories":[{"path":"force-app","default":true}],"namespace":"","sourceApiVersion":"66.0"}
+JSON
+cat > "$source_root/force-app/main/default/objects/AgentWork/AgentWork.object-meta.xml" <<XML
+<?xml version="1.0" encoding="UTF-8"?>
+<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
+    <externalSharingModel>${external_model}</externalSharingModel>
+    <sharingModel>Read</sharingModel>
+</CustomObject>
+XML
+
+if ! deploy_result=$(cd "$source_root" && sf project deploy start \
+    --source-dir force-app/main/default/objects/AgentWork/AgentWork.object-meta.xml \
+    --target-org "$ORG" \
+    --wait 20 \
+    --json 2>&1); then
+  emit_result "blocked" "$previous_model" "$previous_model" "$external_model" false false "" \
+    "The AgentWork sharing metadata deploy failed."
+  exit 1
+fi
+
+deploy_status=$(jq -r '.result.status // empty' <<<"$deploy_result" 2>/dev/null)
+deploy_success=$(jq -r '.result.success // false' <<<"$deploy_result" 2>/dev/null)
+deploy_id=$(jq -r '.result.id // empty' <<<"$deploy_result" 2>/dev/null)
+if [ "$deploy_status" != "Succeeded" ] && [ "$deploy_success" != "true" ]; then
+  emit_result "blocked" "$previous_model" "$previous_model" "$external_model" false false "$deploy_id" \
+    "The AgentWork sharing metadata deploy did not succeed."
+  exit 1
+fi
+
+if ! readback_file=$(retrieve_agent_work "$WORK_DIR/readback"); then
+  emit_result "blocked" "$previous_model" "" "$external_model" true false "$deploy_id" \
+    "The AgentWork sharing read-back could not be retrieved after deployment."
+  exit 1
+fi
+
+readback_model=$(xml_value sharingModel "$readback_file")
+readback_external=$(xml_value externalSharingModel "$readback_file")
+if [ "$readback_model" != "Read" ] || [ "$readback_external" != "$external_model" ]; then
+  emit_result "blocked" "$previous_model" "$readback_model" "$readback_external" true false "$deploy_id" \
+    "The AgentWork sharing read-back did not match the requested internal model or preserved external model."
+  exit 1
+fi
+
+emit_result "configured" "$previous_model" "$readback_model" "$readback_external" true false "$deploy_id" ""

package/skills/service-omni-agent-work-sharing-configure/scripts/tests/_bootstrap.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+
+
+SKILLS_ROOT = Path(__file__).resolve().parents[3]
+SCRIPT = "service-omni-agent-work-sharing-configure/scripts/configure-and-report.sh"
+
+_FAKE_SF = r'''#!/usr/bin/env bash
+sub="${1:-} ${2:-}"; args="$*"
+state_dir="${FAKE_STATE_DIR:?}"
+trace="$state_dir/trace"
+deployed="$state_dir/deployed"
+printf '%s\n' "$args" >> "$trace"
+
+arg_after() {
+  local wanted="$1" previous=""
+  shift
+  for value in "$@"; do
+    if [ "$previous" = "$wanted" ]; then printf '%s' "$value"; return; fi
+    previous="$value"
+  done
+}
+
+case "$sub" in
+  "data query")
+    if printf '%s' "$args" | grep -q "FROM Organization"; then
+      if [ "${FAKE_PRODUCTION:-0}" = "1" ]; then
+        echo '{"status":0,"result":{"records":[{"Id":"00Dxx0000000000EAA","IsSandbox":false,"TrialExpirationDate":null,"OrganizationType":"Enterprise Edition"}]}}'
+      elif [ "${FAKE_DEVELOPER_EDITION:-0}" = "1" ]; then
+        echo '{"status":0,"result":{"records":[{"Id":"00Dxx0000000000EAA","IsSandbox":false,"TrialExpirationDate":null,"OrganizationType":"Developer Edition"}]}}'
+      else
+        echo '{"status":0,"result":{"records":[{"Id":"00Dxx0000000000EAA","IsSandbox":true,"TrialExpirationDate":null,"OrganizationType":"Developer Edition"}]}}'
+      fi
+    fi;;
+  "project retrieve")
+    target_dir=$(arg_after --target-metadata-dir "$@")
+    mkdir -p "$target_dir/unpackaged/unpackaged/objects"
+    model="${FAKE_CURRENT_MODEL:-Private}"
+    if [ -f "$deployed" ]; then model="${FAKE_READBACK_MODEL:-Read}"; fi
+    cat > "$target_dir/unpackaged/unpackaged/objects/AgentWork.object" <<XML
+<?xml version="1.0" encoding="UTF-8"?>
+<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
+    <externalSharingModel>${FAKE_EXTERNAL_MODEL:-Private}</externalSharingModel>
+    <sharingModel>${model}</sharingModel>
+</CustomObject>
+XML
+    echo '{"status":0,"result":{"status":"Succeeded","success":true}}';;
+  "project deploy")
+    : > "$deployed"
+    echo '{"status":0,"result":{"id":"0Afxx0000000001AAA","status":"Succeeded","success":true,"details":{"componentFailures":[]}}}';;
+  *) echo '{"status":0,"result":{}}';;
+esac
+'''
+
+
+def last_json(output: str) -> dict:
+    decoder = json.JSONDecoder()
+    result, index = None, 0
+    while index < len(output):
+        if output[index] not in "{[":
+            index += 1
+            continue
+        try:
+            candidate, end = decoder.raw_decode(output, index)
+            if isinstance(candidate, dict):
+                result = candidate
+            index = end
+        except json.JSONDecodeError:
+            index += 1
+    assert result is not None, output
+    return result
+
+
+class FakeSf:
+    def __init__(self):
+        self.root: Path | None = None
+        self.bin_dir: Path | None = None
+        self.state_dir: Path | None = None
+
+    def __enter__(self):
+        self.root = Path(tempfile.mkdtemp(prefix="agentwork-sharing-fake-sf-"))
+        self.bin_dir = self.root / "bin"
+        self.state_dir = self.root / "state"
+        self.bin_dir.mkdir()
+        self.state_dir.mkdir()
+        executable = self.bin_dir / "sf"
+        executable.write_text(_FAKE_SF)
+        executable.chmod(0o755)
+        return self
+
+    def run(self, args, extra_env=None):
+        assert self.bin_dir is not None and self.state_dir is not None
+        env = dict(os.environ)
+        env["PATH"] = str(self.bin_dir) + os.pathsep + env.get("PATH", "")
+        env["FAKE_STATE_DIR"] = str(self.state_dir)
+        if extra_env:
+            env.update({key: str(value) for key, value in extra_env.items()})
+        proc = subprocess.run(
+            ["bash", str(SKILLS_ROOT / SCRIPT), *args],
+            capture_output=True,
+            text=True,
+            env=env,
+            cwd=str(SKILLS_ROOT),
+        )
+        return proc.returncode, (proc.stdout or "") + (proc.stderr or "")
+
+    def read_state(self, name: str) -> str:
+        assert self.state_dir is not None
+        path = self.state_dir / name
+        return path.read_text() if path.exists() else ""
+
+    def __exit__(self, *_):
+        import shutil
+        if self.root:
+            shutil.rmtree(self.root, ignore_errors=True)

package/skills/service-omni-agent-work-sharing-configure/scripts/tests/test_agent_work_sharing_contracts.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _bootstrap import FakeSf, last_json  # noqa: E402
+
+
+class AgentWorkSharingContractTests(unittest.TestCase):
+    def test_private_model_deploys_read_and_verifies(self):
+        with FakeSf() as fake:
+            rc, output = fake.run(["org", "--confirm-org-wide-visibility"])
+            trace = fake.read_state("trace")
+
+        self.assertEqual(rc, 0, output)
+        self.assertIn("project deploy start", trace)
+        self.assertIn("CustomObject:AgentWork", trace)
+        result = last_json(output)
+        self.assertEqual(result["status"], "configured")
+        self.assertEqual(result["previous_sharing_model"], "Private")
+        self.assertEqual(result["sharing_model"], "Read")
+        self.assertEqual(result["external_sharing_model"], "Private")
+        self.assertTrue(result["changed"])
+
+    def test_read_model_is_reused_without_deploy(self):
+        with FakeSf() as fake:
+            rc, output = fake.run(["org"], {"FAKE_CURRENT_MODEL": "Read"})
+            trace = fake.read_state("trace")
+
+        self.assertEqual(rc, 0, output)
+        self.assertNotIn("project deploy start", trace)
+        result = last_json(output)
+        self.assertEqual(result["status"], "reused")
+        self.assertFalse(result["changed"])
+
+    def test_plan_reports_action_without_deploy(self):
+        with FakeSf() as fake:
+            rc, output = fake.run(["org", "--plan"])
+            trace = fake.read_state("trace")
+
+        self.assertEqual(rc, 2, output)
+        self.assertNotIn("project deploy start", trace)
+        result = last_json(output)
+        self.assertEqual(result["status"], "action_needed")
+        self.assertTrue(result["dry_run"])
+
+    def test_production_blocks_before_deploy(self):
+        with FakeSf() as fake:
+            rc, output = fake.run(
+                ["org", "--confirm-org-wide-visibility"],
+                {"FAKE_PRODUCTION": "1"},
+            )
+            trace = fake.read_state("trace")
+
+        self.assertEqual(rc, 1, output)
+        self.assertNotIn("project deploy start", trace)
+        self.assertIn("production", last_json(output)["blocking_issue"].lower())
+
+    def test_developer_edition_is_safe_for_confirmed_change(self):
+        with FakeSf() as fake:
+            rc, output = fake.run(
+                ["org", "--confirm-org-wide-visibility"],
+                {"FAKE_DEVELOPER_EDITION": "1"},
+            )
+
+        self.assertEqual(rc, 0, output)
+        self.assertEqual(last_json(output)["status"], "configured")
+
+    def test_failed_readback_blocks(self):
+        with FakeSf() as fake:
+            rc, output = fake.run(
+                ["org", "--confirm-org-wide-visibility"],
+                {"FAKE_READBACK_MODEL": "Private"},
+            )
+
+        self.assertEqual(rc, 1, output)
+        result = last_json(output)
+        self.assertEqual(result["status"], "blocked")
+        self.assertIn("read-back", result["blocking_issue"])
+
+    def test_change_requires_explicit_org_wide_confirmation(self):
+        with FakeSf() as fake:
+            rc, output = fake.run(["org"])
+            trace = fake.read_state("trace")
+
+        self.assertEqual(rc, 1, output)
+        self.assertNotIn("project deploy start", trace)
+        self.assertIn("confirm-org-wide-visibility", last_json(output)["blocking_issue"])
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

package/skills/service-omni-base-settings-configure/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: service-omni-base-settings-configure
+description: "Use to enable the five Omni-Channel base settings on a Salesforce org via the Metadata API. The canonical writer scripts/configure-and-report.sh detects, deploys, and re-verifies in one call (run mode) or detects only (plan mode); it is idempotent (deploys only when a toggle is false or missing) and guards writes with a sandbox/CDO/trial/DE safe_to_write check. It always surfaces the UI-only login-behavior gap in its report. Triggers: enable Omni-Channel, turn on Omni base settings, configure OmniChannelSettings, deploy Settings:OmniChannel. Do not use to configure downstream Omni entities (queues, presence, permissions — use the entity-specific skill) or to deploy other Settings types (use platform-metadata-deploy)."
+allowed-tools: Bash Read Write Edit Glob Grep
+metadata:
+  version: "1.0"
+  domains: ["Service"]
+  minApiVersion: "66.0"
+  relatedSkills:
+    - "platform-metadata-deploy"
+    - "service-omni-channel-setup-coordinate"
+  accessCheck:
+    - type: license
+      value: ServiceCloud
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6"
+    - tool: ["sf"]
+      semver: ">=2.139.6"
+---
+
+# service-omni-base-settings-configure
+
+Enable the five `OmniChannelSettings` booleans (`enableOmniChannel`, `enableOmniAutoLoginPrompt`, `enableOmniSecondaryRoutingPriority`, `enableOmniSkillsRouting`, `enableOmniStatusCapModel`) via a single Metadata API deploy. Nothing downstream — queues, presence statuses, routing flows — works without `enableOmniChannel=true`, so this must be the first write in an Omni setup sequence. The skill probes first and deploys only when a toggle is false or missing.
+
+## Inputs
+
+```bash
+bash scripts/configure-and-report.sh run  <org-alias>   # detect; deploy if needed; re-verify
+bash scripts/configure-and-report.sh plan <org-alias>   # read-only: detect only, never deploys
+```
+
+`org-alias` is the only input. All five toggles are always set to `true` — the skill takes no per-toggle overrides; a caller who wants a subset should use `platform-metadata-deploy` with their own `OmniChannel.settings-meta.xml`.
+
+## Preconditions and safety
+
+- Target org authenticated via `sf` CLI (My Domain URL, not `.lightning.force.com`), Service Cloud license present, `sf` CLI ≥ 2.139.6.
+- **Production guardrail:** the writer 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. This permits CDOs (`IsSandbox=false` with a non-null `TrialExpirationDate`); do not weaken it to a bare `IsSandbox` check.
+
+## Run
+
+`configure-and-report.sh` is the canonical entry point:
+
+- **run** — probe; if all five are already enabled, emit `reused` (no deploy); otherwise run the `safe_to_write` guard, deploy the explicit `assets/force-app/main/default/settings/OmniChannel.settings-meta.xml` source file with all five `true` (a `SucceededPartial` is treated as failure), re-probe, and emit `configured` iff all five are now true, else `blocked`. The explicit source path bypasses source-tracking no-op decisions when the org value has drifted.
+- **plan** — probe only; emit `reused` if all enabled, else `action_needed`. Never deploys.
+
+The probe retrieves `Settings:OmniChannel` and takes 1–2 minutes (Metadata retrieve is slow); this is expected. The deploy runs from `assets/` (a valid DX project) and names the settings file with `--source-dir`; its template is never mutated at runtime, so the skill stays reproducible and does not report "No local changes to deploy" solely because local source tracking is clean.
+
+## Behavior
+
+**Whole-document writes.** `Settings` is a whole-document metadata type — the Metadata API does not accept partial updates, so the skill always deploys the full file rather than PATCHing individual toggles.
+
+**Login-behavior gap.** The Omni login-behavior radio (Setup → Omni-Channel Settings → "Define login behavior when an agent opens a new window/tab") has no public API on v66. The report always surfaces its click-path — even on a no-op `reused` run — so a "nothing to do" result never hides the one manual action. `enableOmniAutoLoginPrompt` still deploys cleanly (other Omni features may depend on it internally) but does not drive that radio.
+
+**Fail-closed verify.** After a deploy the skill re-probes and requires all five toggles true; a deploy that reports success but does not stick (an uncommon org-level restriction) blocks rather than reporting success.
+
+## Output contract
+
+`configure-and-report.sh` emits a single JSON object with `status` ∈ `configured` | `reused` | `action_needed` | `blocked`, a top-level `all_enabled` boolean the coordinator reads to gate downstream skills, full `before`/`after` toggle objects, `deploy_id`, `safe_to_write`, `manual_actions`, and `blocking_issue`.
+
+- `configured` — a toggle was false, the deploy ran, and the re-probe shows all true (run mode).
+- `reused` — all five were already true; no deploy.
+- `action_needed` — plan mode saw a disabled toggle; nothing deployed.
+- `blocked` — `safe_to_write=false`, the deploy failed or was `SucceededPartial`, or the re-probe still shows a false toggle.
+
+`manual_actions` always includes the login-behavior gap entry on non-blocked reports; `deploy_id` is `null` for `reused`/`action_needed`; `blocking_issue` names the failure only when `status: blocked`.
+
+## Limitations
+
+- Configures only `OmniChannelSettings`, always with all five toggles true — other `Settings` types belong to `platform-metadata-deploy`.
+- Cannot turn the login-behavior radio (no public API on v66) — it only surfaces the click-path.
+
+## References
+
+| File | When to read |
+|---|---|
+| `references/api-notes.md` | Before a deploy — the five toggles' semantics, dependencies, and the login-behavior caveat |

package/skills/service-omni-base-settings-configure/assets/force-app/main/default/settings/OmniChannel.settings-meta.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<OmniChannelSettings xmlns="http://soap.sforce.com/2006/04/metadata">
+    <enableOmniAutoLoginPrompt>true</enableOmniAutoLoginPrompt>
+    <enableOmniChannel>true</enableOmniChannel>
+    <enableOmniSecondaryRoutingPriority>true</enableOmniSecondaryRoutingPriority>
+    <enableOmniSkillsRouting>true</enableOmniSkillsRouting>
+    <enableOmniStatusCapModel>true</enableOmniStatusCapModel>
+</OmniChannelSettings>

package/skills/service-omni-base-settings-configure/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>OmniChannel</members>
+        <name>Settings</name>
+    </types>
+    <version>66.0</version>
+</Package>

package/skills/service-omni-base-settings-configure/assets/sfdx-project.json

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

package/skills/service-omni-base-settings-configure/references/api-notes.md

@@ -0,0 +1,121 @@
+# OmniChannelSettings — API notes
+
+Load this reference **only when a deploy is actually needed** (i.e., after `detect-existing.sh` returned `all_enabled: false`). It covers the five toggles' semantics, cross-field validators, and the login-behavior UI-only caveat.
+
+**Metadata type:** `Settings` with name `OmniChannel` (deployed as `Settings:OmniChannel`).
+**API version verified:** v66 (Summer '26 baseline).
+**Whole-document type:** always deploy the full XML, never PATCH individual toggles.
+
+---
+
+## The five toggles
+
+All five ship as `true` in this skill's `assets/force-app/main/default/settings/OmniChannel.settings-meta.xml`. This skill does not accept per-toggle overrides — a user who wants a subset should invoke `platform-metadata-deploy` directly with their own XML.
+
+### 1. `enableOmniChannel` (master switch)
+
+**Effect:** Enables the Omni-Channel feature on the org. When `false`, no downstream Omni entity can be created (`ServicePresenceStatus`, `PresenceUserConfig`, `QueueRoutingConfig`, `WorkSkillRouting`, etc. all reject with `INVALID_TYPE`).
+
+**Values:** `true` | `false`.
+
+**Dependencies:** Must be `true` for any of the other four toggles to have meaningful effect.
+
+**Reversibility:** Setting to `false` after enablement is not blocked, but is destructive — existing Omni entities remain but stop routing work. Do not disable in a production-like environment without explicit user acknowledgement.
+
+### 2. `enableOmniSkillsRouting`
+
+**Effect:** Enables skills-based routing. Required for:
+- `WorkSkillRouting` rules to fire
+- `routeWork` action in Flow with `routingType=SkillsBased`
+- `Skill` records to influence work-item assignment
+
+**Values:** `true` | `false`.
+
+**Dependencies:** Requires `enableOmniChannel=true`.
+
+### 3. `enableOmniSecondaryRoutingPriority`
+
+**Effect:** Enables the secondary routing priority field on queue routing configurations. Allows two-level priority sorting when multiple work items match the same queue.
+
+**Values:** `true` | `false`.
+
+**Dependencies:** Requires `enableOmniChannel=true`.
+
+### 4. `enableOmniStatusCapModel`
+
+**Effect:** Enables the status-based capacity model on `ServiceChannel`. When true, agents can have different capacity ceilings based on which presence status they are in.
+
+**Values:** `true` | `false`.
+
+**Dependencies:** Requires `enableOmniChannel=true`.
+
+### 5. `enableOmniAutoLoginPrompt` (⚠ caveat — see below)
+
+**Effect (documented):** Should control the Omni-Channel login-prompt behavior when an agent opens a new window/tab.
+
+**Effect (observed):** Deploys cleanly and round-trips through retrieve — but does **not** drive the UI radio at *Setup → Omni-Channel Settings → "Define login behavior when an agent using Omni-Channel opens a new window or tab"*. Flipping the value `true`/`false` re-retrieves the same value while the UI radio stays unchanged. The login-behavior radio is not reachable through this metadata field.
+
+**Values:** `true` | `false`.
+
+**Dependencies:** Requires `enableOmniChannel=true`.
+
+**This skill still deploys the toggle as `true`.** The XML deploys cleanly and other Omni features may depend on it internally; not shipping it would be an incomplete base-settings deploy.
+
+---
+
+## Cross-field validators
+
+The Metadata API does **not** enforce cross-field validators on `OmniChannelSettings` — every combination of the five booleans is accepted by the deploy. However, functional dependencies exist at runtime:
+
+| If this is `true` | Then this must also be `true` (for the feature to actually work) |
+|---|---|
+| `enableOmniSkillsRouting` | `enableOmniChannel` |
+| `enableOmniSecondaryRoutingPriority` | `enableOmniChannel` |
+| `enableOmniStatusCapModel` | `enableOmniChannel` |
+| `enableOmniAutoLoginPrompt` | `enableOmniChannel` |
+
+Since this skill sets all five to `true`, the dependencies are automatically satisfied.
+
+---
+
+## Deploy metadata name
+
+```text
+Settings:OmniChannel
+```
+
+Command:
+
+```bash
+cd assets
+sf project deploy start --target-org <org-alias> --metadata "Settings:OmniChannel" --json
+```text
+
+Expected response:
+
+```json
+{
+  "status": 0,
+  "result": {
+    "id": "0AfRZ000001Yhef0AC",
+    "status": "Succeeded",
+    "success": true,
+    "numberComponentsDeployed": 1,
+    "numberComponentsTotal": 1
+  }
+}
+```
+
+**Failure modes:**
+
+- `status: Failed` + `componentFailures[0].problem: "Namespace: unable to deploy ..."` — org does not have Omni-Channel provisioned at all. Rare on Service Cloud orgs; possible on stripped-down trial orgs. Fail the skill; the user must contact Salesforce for org-shape correction.
+- `UNKNOWN_EXCEPTION` during retrieve or deploy — transient server-side error. Retry once before failing.
+- `LightningDomain` error on retrieve/deploy — org was authenticated with the `.lightning.force.com` URL instead of the My Domain URL. Re-authenticate with the My Domain URL. This is an auth bug, not an API issue.
+
+---
+
+## Login-behavior UI-only gap (surface always)
+
+The `enableOmniAutoLoginPrompt` toggle does not drive the *Setup → Omni-Channel Settings → "Define login behavior when an agent opens a new window/tab"* three-way radio. The full write-up (root cause, coordinator behavior) lives in the `service-omni-channel-setup-coordinate` skill's gap catalog reference.
+
+**Skill behavior:** always include the login-behavior click-path in the report's `manual_actions` array, even for `reused` (no-op) runs. The operator may still need to click the radio manually to select their preferred behavior.