@salesforce/afv-skills 1.55.0 → 1.57.0

package/skills/service-omni-channel-inventory-analyze/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: service-omni-channel-inventory-analyze
+description: "Use to inventory configured Omni-Channel instances across Voice, Email, Chat, SMS, Facebook, WhatsApp, and In-App, including each channel's Queue, Flow, or Other routing target, without changing the org. TRIGGER when: list Omni channels, inventory Omni routing, inspect channel routing targets, analyze Omni-Channel setup, or find configured service channels. Do not use to create, update, activate, or delete channels or routing configuration."
+allowed-tools: Bash Read Write Grep Glob
+metadata:
+  version: "1.0"
+  domains: ["Service"]
+  minApiVersion: "66.0"
+  relatedSkills:
+    - "service-omni-channel-setup-coordinate"
+    - "service-omni-queue-routing-config-deploy"
+    - "service-omni-routing-flow-deploy"
+    - "service-omni-service-channel-configure"
+  accessCheck:
+    - type: license
+      value: ServiceCloud
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6"
+    - tool: ["python3"]
+      semver: ">=3.8"
+    - tool: ["sf"]
+      semver: ">=2.139.6"
+---
+
+# service-omni-channel-inventory-analyze
+
+Read the org's complete Omni-Channel setup-home inventory without making changes. The supported headless operation combines Voice, Email, Live Chat, and Messaging channel families and returns their derived routing type and routing target. Use this analyzer before changing an unfamiliar org or when a user asks what Omni channels and routing are already configured.
+
+## Inputs
+
+```bash
+bash scripts/analyze.sh <org-alias> [--type Voice|Email|Chat|SMS|Facebook|WhatsApp|InApp]
+```
+
+- `org-alias` is required and must already be authenticated with Salesforce CLI.
+- `--type` is optional and case-insensitive. It filters the returned inventory without changing the source data.
+
+## Preconditions and safety
+
+- Target org authenticated through `sf` CLI.
+- API v66.0 or later.
+- The running user must have **View Setup and Configuration** and **Customize Application**.
+- This skill is read-only. The shared Headless dispatcher uses an HTTP POST envelope, but the invoked `getChannelInstances` controller action performs no org mutation.
+- Use `sf api request rest`; never extract or print an access token.
+
+## Run
+
+Invoke `scripts/analyze.sh` with the target org and optional channel type. The script POSTs the approved `OmniChannelInstancesController.getChannelInstances` envelope to the shared Headless dispatcher, validates the inner response, optionally filters it, and returns a stable summary plus the matching channel instances.
+
+The inventory includes these source fields when the platform supplies them:
+
+| Field | Meaning |
+|---|---|
+| `id`, `label` | Channel identity and display label |
+| `omniChannelInstanceType` | Voice, Email, Chat, SMS, Facebook, WhatsApp, or InApp |
+| `routingType` | Queue, Flow, or Other |
+| `routingRequirementId`, `routingRequirementLabel` | Queue, flow, or other routing target |
+| `channelUrl`, `routingRequirementUrl` | Setup navigation links synthesized by the platform |
+| `icon`, `messages` | Display metadata and platform-provided notices |
+
+## Output contract
+
+The script emits one JSON object:
+
+- `skill`: `service-omni-channel-inventory-analyze`
+- `status`: `analyzed` or `blocked`
+- `filter`: canonical channel type or `null`
+- `summary.total_configured`: number of instances returned by the platform before filtering
+- `summary.returned`: number of instances in `instances`
+- `summary.by_channel_type`: counts for the returned inventory
+- `summary.by_routing_type`: Queue, Flow, and Other counts for the returned inventory
+- `instances`: normalized channel instance objects
+- `blocking_issue`: actionable failure reason or `null`
+
+An empty `instances` array with `status: analyzed` is a valid inventory result. Authentication, authorization, endpoint, or malformed-response failures return `status: blocked` and exit non-zero; never reinterpret them as an empty org.
+
+## Boundaries
+
+- Do not replace this operation with independent SOQL queries. No single public object API reproduces the platform's cross-family aggregation, routing-type derivation, and setup URL generation.
+- Do not infer missing routing fields. Preserve `null` when the platform does not supply a value.
+- Do not use the returned setup URLs as mutation endpoints.
+- For configuration changes, hand off to the appropriate leaf skill only after presenting the inventory to the user.
+
+| Requested follow-up | Skill |
+|---|---|
+| Coordinate a complete Omni setup | `service-omni-channel-setup-coordinate` |
+| Create or reuse a Service Channel | `service-omni-service-channel-configure` |
+| Create or update a queue routing configuration | `service-omni-queue-routing-config-deploy` |
+| Deploy a QueueBased or SkillsBased routing flow | `service-omni-routing-flow-deploy` |
+
+## References
+
+| File | When to read |
+|---|---|
+| `references/api-notes.md` | Supported endpoint, permission boundary, response fields, and why the headless operation is canonical |

package/skills/service-omni-channel-inventory-analyze/references/api-notes.md

@@ -0,0 +1,52 @@
+# Omni-Channel inventory API notes
+
+## Supported operation
+
+```text
+POST /services/data/v66.0/headless/invoke
+```
+
+Call it through `sf api request rest --method POST --target-org <alias>` with this invoke envelope:
+
+```json
+{
+  "className": "ui.omnichannel.home.controller.OmniChannelInstancesController",
+  "action": "getChannelInstances"
+}
+```
+
+The Project Codey route is logically read-only even though the shared dispatcher transport is POST-only. Salesforce CLI owns authentication, so do not extract the org access token or build an Authorization header. Treat the inner `status_code` as authoritative and read the inventory from `body`.
+
+Project Codey's approved `OmniChannelHome` source-of-record identifies this Aura-backed headless operation as canonical. The owning-team review was approved on 2026-08-20. The operation aggregates providers for Live Chat buttons, Messaging channels, Service channels, and Voice, then derives routing labels and setup URLs. Independent Connect, Tooling, Metadata, or sObject calls do not reproduce that contract.
+
+## Permission boundary
+
+The running user needs both customer-facing permissions:
+
+- View Setup and Configuration
+- Customize Application
+
+A permission failure is not evidence that the org has no channel instances. Return `status: blocked` and ask the user to run with an appropriately authorized setup user.
+
+## Response fields
+
+Each channel instance can include:
+
+```text
+id
+label
+channelUrl
+omniChannelInstanceType
+routingType
+icon
+routingRequirementId
+routingRequirementLabel
+routingRequirementUrl
+messages
+```
+
+Known channel-type labels are `Voice`, `Email`, `Chat`, `SMS`, `Facebook`, `WhatsApp`, and `InApp`. Known routing labels are `Queue`, `Flow`, and `Other`. The script accepts these labels case-insensitively and emits their canonical display spelling.
+
+## Response handling
+
+The supported operation's contract is an array of channel instances. The analyzer also tolerates a raw array or the same array nested under a standard `body`, `result`, `data`, `items`, `records`, `value`, or `channelInstances` envelope so Salesforce CLI response wrapping does not silently turn valid results into failures. Any other shape is blocked as malformed.

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

@@ -0,0 +1,185 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  echo "Usage: bash analyze.sh <org-alias> [--type Voice|Email|Chat|SMS|Facebook|WhatsApp|InApp]" >&2
+}
+
+emit_blocked() {
+  local issue="$1"
+  jq -n \
+    --argjson filter "$FILTER_JSON" \
+    --arg issue "$issue" \
+    '{
+      skill: "service-omni-channel-inventory-analyze",
+      status: "blocked",
+      filter: $filter,
+      summary: {total_configured: null, returned: 0, by_channel_type: {}, by_routing_type: {}},
+      instances: [],
+      blocking_issue: $issue
+    }'
+}
+
+canonical_type() {
+  local normalized
+  normalized=$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]')
+  case "$normalized" in
+    voice) echo "Voice" ;;
+    email) echo "Email" ;;
+    chat) echo "Chat" ;;
+    sms) echo "SMS" ;;
+    facebook) echo "Facebook" ;;
+    whatsapp) echo "WhatsApp" ;;
+    inapp) echo "InApp" ;;
+    *) return 1 ;;
+  esac
+}
+
+if [ $# -lt 1 ]; then
+  usage
+  exit 1
+fi
+
+ORG="$1"
+shift
+FILTER=""
+FILTER_JSON="null"
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --type)
+      if [ $# -lt 2 ] || [ -z "$2" ]; then
+        usage
+        exit 1
+      fi
+      if ! FILTER=$(canonical_type "$2"); then
+        FILTER_JSON="null"
+        emit_blocked "Unsupported channel type '$2'. Use Voice, Email, Chat, SMS, Facebook, WhatsApp, or InApp."
+        exit 1
+      fi
+      FILTER_JSON=$(jq -n --arg value "$FILTER" '$value')
+      shift 2
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+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-inventory.XXXXXX")
+trap 'rm -rf "$WORK_DIR"' EXIT
+RAW_RESPONSE="$WORK_DIR/response.json"
+ERROR_RESPONSE="$WORK_DIR/error.txt"
+ENDPOINT="/services/data/v66.0/headless/invoke"
+INVOKE_BODY=$(jq -cn '{
+  className:"ui.omnichannel.home.controller.OmniChannelInstancesController",
+  action:"getChannelInstances"
+}')
+
+if ! FORCE_COLOR=0 sf api request rest "$ENDPOINT" \
+  --method POST \
+  --body "$INVOKE_BODY" \
+  --target-org "$ORG" \
+  >"$RAW_RESPONSE" 2>"$ERROR_RESPONSE"; then
+  if grep -qiE 'insufficient|permission|access denied|forbidden' "$ERROR_RESPONSE"; then
+    emit_blocked "The inventory read was denied. Run it as a user with View Setup and Configuration and Customize Application."
+  else
+    emit_blocked "The supported Omni-Channel inventory operation failed. Verify org connectivity and feature availability, then retry."
+  fi
+  exit 1
+fi
+
+if ! jq -e . "$RAW_RESPONSE" >/dev/null 2>&1; then
+  emit_blocked "The inventory operation returned malformed JSON. No channel state was inferred."
+  exit 1
+fi
+
+INNER_STATUS=$(jq -r 'if type=="object" then .status_code // empty else empty end' "$RAW_RESPONSE")
+if [ -n "$INNER_STATUS" ] && { ! [[ "$INNER_STATUS" =~ ^[0-9]+$ ]] || [ "$INNER_STATUS" -lt 200 ] || [ "$INNER_STATUS" -ge 300 ]; }; then
+  INNER_ERROR=$(jq -r '.body.message // .body[0].message // .body.error // "unknown error"' "$RAW_RESPONSE")
+  if printf '%s' "$INNER_ERROR" | grep -qiE 'insufficient|permission|access denied|forbidden'; then
+    emit_blocked "The inventory read was denied. Run it as a user with View Setup and Configuration and Customize Application."
+  else
+    emit_blocked "The supported Omni-Channel inventory operation failed: $INNER_ERROR."
+  fi
+  exit 1
+fi
+
+EXTRACT_FILTER='def inventory:
+  if type == "array" then .
+  elif (.body? | type) == "array" then .body
+  elif (.channelInstances? | type) == "array" then .channelInstances
+  elif (.result? | type) == "array" then .result
+  elif (.result?.channelInstances? | type) == "array" then .result.channelInstances
+  elif (.data? | type) == "array" then .data
+  elif (.items? | type) == "array" then .items
+  elif (.records? | type) == "array" then .records
+  elif (.value? | type) == "array" then .value
+  else null
+  end;
+inventory'
+
+if ! jq -e "$EXTRACT_FILTER | type == \"array\" and all(.[]; type == \"object\")" "$RAW_RESPONSE" >/dev/null 2>&1; then
+  emit_blocked "The inventory operation returned an unsupported response shape. No channel state was inferred."
+  exit 1
+fi
+
+jq \
+  --arg filter "$FILTER" \
+  "$EXTRACT_FILTER as \$source |
+  def channel_type:
+    (. // null) as \$value |
+    if (\$value | type) != \"string\" then null
+    elif (\$value | ascii_downcase) == \"voice\" then \"Voice\"
+    elif (\$value | ascii_downcase) == \"email\" then \"Email\"
+    elif (\$value | ascii_downcase) == \"chat\" then \"Chat\"
+    elif (\$value | ascii_downcase) == \"sms\" then \"SMS\"
+    elif (\$value | ascii_downcase) == \"facebook\" then \"Facebook\"
+    elif (\$value | ascii_downcase) == \"whatsapp\" then \"WhatsApp\"
+    elif (\$value | ascii_downcase) == \"inapp\" then \"InApp\"
+    else \$value
+    end;
+  def routing_type:
+    (. // null) as \$value |
+    if (\$value | type) != \"string\" then null
+    elif (\$value | ascii_downcase) == \"queue\" then \"Queue\"
+    elif (\$value | ascii_downcase) == \"flow\" then \"Flow\"
+    elif (\$value | ascii_downcase) == \"other\" then \"Other\"
+    else \$value
+    end;
+  [\$source[] | {
+    id: (.id // null),
+    label: (.label // null),
+    channelUrl: (.channelUrl // null),
+    omniChannelInstanceType: (.omniChannelInstanceType | channel_type),
+    routingType: (.routingType | routing_type),
+    icon: (.icon // null),
+    routingRequirementId: (.routingRequirementId // null),
+    routingRequirementLabel: (.routingRequirementLabel // null),
+    routingRequirementUrl: (.routingRequirementUrl // null),
+    messages: (if (.messages | type) == \"array\" then .messages else [] end)
+  }] as \$all |
+  (if \$filter == \"\" then \$all else [\$all[] | select(.omniChannelInstanceType == \$filter)] end) as \$returned |
+  {
+    skill: \"service-omni-channel-inventory-analyze\",
+    status: \"analyzed\",
+    filter: (if \$filter == \"\" then null else \$filter end),
+    summary: {
+      total_configured: (\$all | length),
+      returned: (\$returned | length),
+      by_channel_type: (reduce \$returned[] as \$item ({}; .[(\$item.omniChannelInstanceType // \"Unknown\")] += 1)),
+      by_routing_type: (reduce \$returned[] as \$item ({}; .[(\$item.routingType // \"Unknown\")] += 1))
+    },
+    instances: \$returned,
+    blocking_issue: null
+  }" "$RAW_RESPONSE"

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

@@ -0,0 +1,84 @@
+"""Fake Salesforce CLI harness for the Omni-Channel inventory 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-inventory-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":{}}'
+    ;;
+  "api request")
+    printf '%s\n' "$*" >> "${FAKE_SF_LOG:?}"
+    if [ "${FAKE_API_STATUS:-ok}" = "fail" ]; then
+      echo "${FAKE_API_ERROR:-request failed}" >&2
+      exit 1
+    fi
+    printf '%s\n' "${FAKE_API_BODY:-[]}"
+    ;;
+  *)
+    echo '{"status":1,"message":"unexpected command"}' >&2
+    exit 1
+    ;;
+esac
+'''
+
+
+class FakeSf:
+    def __enter__(self):
+        self._directory = tempfile.mkdtemp(prefix="omni-inventory-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_API_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-inventory-analyze/scripts/tests/test_inventory_analyze_contracts.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import unittest
+
+from _bootstrap import FakeSf, last_json
+
+
+CHANNELS = [
+    {
+        "id": "0N9xx0000000001AAA",
+        "label": "Case Email",
+        "channelUrl": "/lightning/setup/ServiceChannelSettings/page?address=one",
+        "omniChannelInstanceType": "EMAIL",
+        "routingType": "QUEUE",
+        "routingRequirementId": "00Gxx0000000001AAA",
+        "routingRequirementLabel": "Case Queue",
+        "routingRequirementUrl": "/lightning/setup/Queues/page?address=one",
+        "messages": [],
+    },
+    {
+        "id": "0M0xx0000000002AAA",
+        "label": "Support Voice",
+        "omniChannelInstanceType": "Voice",
+        "routingType": "Flow",
+        "routingRequirementLabel": "Voice Routing",
+        "messages": [{"severity": "info"}],
+    },
+]
+
+
+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_type_is_blocked_before_api_call(self):
+        with FakeSf() as fake:
+            return_code, output, commands = fake.run(["org", "--type", "CarrierPigeon"])
+        self.assertEqual(return_code, 1, output)
+        result = last_json(output)
+        self.assertEqual(result["status"], "blocked")
+        self.assertIn("Unsupported channel type", result["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 InventoryContractTests(unittest.TestCase):
+    def test_raw_array_is_normalized_and_summarized(self):
+        with FakeSf() as fake:
+            return_code, output, commands = fake.run(["org"], FAKE_API_BODY=CHANNELS)
+        self.assertEqual(return_code, 0, output)
+        result = last_json(output)
+        self.assertEqual(result["status"], "analyzed")
+        self.assertEqual(result["summary"]["total_configured"], 2)
+        self.assertEqual(result["summary"]["returned"], 2)
+        self.assertEqual(result["summary"]["by_channel_type"], {"Email": 1, "Voice": 1})
+        self.assertEqual(result["summary"]["by_routing_type"], {"Flow": 1, "Queue": 1})
+        self.assertIn("--method POST", commands)
+        self.assertIn(
+            "/services/data/v66.0/headless/invoke",
+            commands,
+        )
+        self.assertIn("OmniChannelInstancesController", commands)
+        self.assertIn("getChannelInstances", commands)
+        self.assertNotRegex(commands, r"--method (GET|PATCH|DELETE)")
+
+    def test_direct_invocation_envelope_is_unwrapped(self):
+        with FakeSf() as fake:
+            return_code, output, _ = fake.run(
+                ["org"],
+                FAKE_API_BODY={"status_code": 200, "body": CHANNELS},
+            )
+        self.assertEqual(return_code, 0, output)
+        result = last_json(output)
+        self.assertEqual(result["status"], "analyzed")
+        self.assertEqual(result["summary"]["total_configured"], 2)
+
+    def test_type_filter_is_case_insensitive(self):
+        with FakeSf() as fake:
+            return_code, output, _ = fake.run(["org", "--type", "voice"], FAKE_API_BODY={"result": CHANNELS})
+        self.assertEqual(return_code, 0, output)
+        result = last_json(output)
+        self.assertEqual(result["filter"], "Voice")
+        self.assertEqual(result["summary"]["total_configured"], 2)
+        self.assertEqual(result["summary"]["returned"], 1)
+        self.assertEqual(result["instances"][0]["label"], "Support Voice")
+
+    def test_empty_inventory_is_valid(self):
+        with FakeSf() as fake:
+            return_code, output, _ = fake.run(["org"], FAKE_API_BODY=[])
+        self.assertEqual(return_code, 0, output)
+        result = last_json(output)
+        self.assertEqual(result["status"], "analyzed")
+        self.assertEqual(result["instances"], [])
+        self.assertEqual(result["summary"]["total_configured"], 0)
+
+    def test_permission_failure_is_not_reported_as_empty(self):
+        with FakeSf() as fake:
+            return_code, output, _ = fake.run(
+                ["org"],
+                FAKE_API_STATUS="fail",
+                FAKE_API_ERROR="INSUFFICIENT_ACCESS: permission denied",
+            )
+        self.assertEqual(return_code, 1, output)
+        result = last_json(output)
+        self.assertEqual(result["status"], "blocked")
+        self.assertIsNone(result["summary"]["total_configured"])
+        self.assertIn("View Setup", result["blocking_issue"])
+
+    def test_inner_dispatch_failure_is_blocked(self):
+        with FakeSf() as fake:
+            return_code, output, _ = fake.run(
+                ["org"],
+                FAKE_API_BODY={"status_code": 403, "body": {"message": "permission denied"}},
+            )
+        self.assertEqual(return_code, 1, output)
+        result = last_json(output)
+        self.assertEqual(result["status"], "blocked")
+        self.assertIn("View Setup", result["blocking_issue"])
+
+    def test_malformed_response_is_blocked(self):
+        with FakeSf() as fake:
+            return_code, output, _ = fake.run(["org"], FAKE_API_BODY={"unexpected": "shape"})
+        self.assertEqual(return_code, 1, output)
+        result = last_json(output)
+        self.assertEqual(result["status"], "blocked")
+        self.assertIn("unsupported response shape", result["blocking_issue"])
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

package/skills/service-omni-channel-limits-analyze/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: service-omni-channel-limits-analyze
+description: "Use to report Omni-Channel Pending Service Routing usage without changing the org: query the current PendingServiceRouting count, compare it with an admin-supplied maximum or a labeled routing-model reference default, and explain which live values are unavailable through supported APIs. TRIGGER when: check Omni-Channel limits, inspect PSR limits, analyze PendingServiceRouting usage, review pending routing capacity, or report queued work usage. Do not use to change limits or scrape Salesforce Setup."
+allowed-tools: Bash Read Write Grep Glob
+metadata:
+  version: "1.0"
+  domains: ["Service"]
+  minApiVersion: "66.0"
+  relatedSkills:
+    - "service-omni-channel-inventory-analyze"
+    - "service-omni-channel-setup-coordinate"
+  accessCheck:
+    - type: license
+      value: ServiceCloud
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6"
+    - tool: ["python3"]
+      semver: ">=3.8"
+    - tool: ["sf"]
+      semver: ">=2.139.6"
+---
+
+# service-omni-channel-limits-analyze
+
+Report the Pending Service Routing usage that can be obtained safely through supported customer-org APIs. The Salesforce **Setup → Omni-Channel → Limits** page is read-only and also displays internal values that are not exposed through REST, Tooling, Metadata, or Connect APIs. This skill reports the live PSR count and labels every non-verifiable value explicitly.
+
+## Inputs
+
+```bash
+bash scripts/analyze.sh <org-alias> [--routing-model enhanced|legacy] [--max-psrs <integer>]
+```
+
+- `org-alias` is required and must already be authenticated with Salesforce CLI.
+- `--routing-model` defaults to `enhanced`. It selects only the reference maximum used when `--max-psrs` is absent.
+- `--max-psrs` accepts an administrator-provided maximum from 1 through 1,000,000. It is still labeled as not API-verified.
+
+## Run
+
+Invoke `scripts/analyze.sh` with the target org and rely on its JSON result for the live count, labeled comparison values, unavailable hourly values, and blocking details. The script invokes `sf org display` and `sf data query` internally; do not reproduce their query or calculation logic outside the script.
+
+To verify the bundled script contract after a change, run `python3 scripts/tests/test_limits_analyze_contracts.py`; the test module loads its local `scripts/tests/_bootstrap.py` fixture automatically.
+
+## Output contract
+
+The script emits one JSON object:
+
+- `skill`: `service-omni-channel-limits-analyze`
+- `status`: `analyzed` or `blocked`
+- `routing_model`: `enhanced` or `legacy`
+- `metrics.current_pending_service_routings`: live count, comparison maximum, approximate percentage, and source labels
+- `metrics.pending_service_routing_rate_per_hour`: unavailable live value, reference maximum, and source labels
+- `caveats`: mandatory accuracy boundaries
+- `blocking_issue`: actionable failure reason or `null`
+
+If `PendingServiceRouting` cannot be queried, return `status: blocked`. Do not reinterpret an unavailable object, missing feature, or permission failure as zero usage.
+
+## Boundaries
+
+- Never scrape, replay, or submit the Visualforce Setup page. Its session state and controller are not a supported customer API.
+- Never describe a reference default as the org's configured maximum.
+- Never fabricate the live hourly rate or compute its utilization percentage.
+- Never mutate routing, queues, agents, limits, or metadata.
+- Treat the PSR count as a point-in-time snapshot that can change while work is routed.
+- For a complete channel and routing inventory, use `service-omni-channel-inventory-analyze`.
+- For a user-approved end-to-end Omni setup, hand off to `service-omni-channel-setup-coordinate`; this limits analyzer remains read-only.
+
+## Reference
+
+Read `references/api-notes.md` when explaining why the report cannot exactly reproduce every value on the Setup page.

package/skills/service-omni-channel-limits-analyze/references/api-notes.md

@@ -0,0 +1,22 @@
+# Omni-Channel limits API notes
+
+## Supported value
+
+`SELECT COUNT() FROM PendingServiceRouting` provides a live, point-in-time PSR row count when Omni-Channel is enabled and the running user can access the object.
+
+## Values not exposed by a supported API
+
+The read-only Omni-Channel Limits Setup page also displays the org's effective maximum PSR count and a rolling hourly enqueue meter. Those values are read by Salesforce's internal page controller and are not exposed as fields on `PendingServiceRouting`, Tooling objects, Metadata types, Connect resources, or the standard REST org-limits response.
+
+The skill therefore uses these values only as labeled references:
+
+| Routing model | Reference maximum PSRs |
+|---|---:|
+| Enhanced | 300,000 |
+| Legacy | 200,000 |
+
+The reference hourly maximum is 45,000. Actual org values can differ, and live hourly usage is not retrievable. An administrator can supply a known PSR maximum with `--max-psrs`, but the script still records that it was not verified through an API.
+
+## Full-fidelity product path
+
+Exact reporting requires a Salesforce Core product API that exposes both maximums and the rolling hourly meter, ideally through the standard REST org-limits resource. Until that contract exists, do not scrape Setup HTML or model a fictional limits sObject.