@salesforce/afv-skills 1.47.0 → 1.48.0

package/skills/service-omni-base-settings-configure/scripts/configure-and-report.sh

@@ -0,0 +1,164 @@
+#!/usr/bin/env bash
+# configure-and-report.sh - WRITE entry point (plan|run): detect the five OmniChannelSettings toggles and, when any are off and safe_to_write, deploy canonical settings + re-verify. Args, JSON status contract, exit codes: SKILL.md.
+
+set -euo pipefail
+
+if [ $# -lt 2 ]; then
+  echo '{"status":"blocked","blocking_issue":"Missing required args","usage":"bash configure-and-report.sh <plan|run> <org-alias>"}' >&2
+  exit 1
+fi
+
+MODE="$1"
+ORG="$2"
+
+case "$MODE" in
+  plan|run) ;;
+  *)
+    echo "{\"status\":\"blocked\",\"blocking_issue\":\"Invalid mode '$MODE'. Expected 'plan' or 'run'.\"}" >&2
+    exit 1
+    ;;
+esac
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+DETECT_SCRIPT="$SCRIPT_DIR/detect-existing.sh"
+ASSETS_DIR="$(cd "$SCRIPT_DIR/../assets" && pwd)"
+
+if [ ! -f "$DETECT_SCRIPT" ]; then
+  echo "{\"status\":\"blocked\",\"blocking_issue\":\"Sibling script not found: $DETECT_SCRIPT\"}" >&2
+  exit 1
+fi
+
+# Step 1 - detect current settings
+DETECT_EXIT=0
+BEFORE_JSON=$(bash "$DETECT_SCRIPT" "$ORG" 2>&1) || DETECT_EXIT=$?
+
+if [ "$DETECT_EXIT" -ne 0 ] || ! echo "$BEFORE_JSON" | jq -e . >/dev/null 2>&1; then
+  jq -n --arg raw "$BEFORE_JSON" --argjson exit "$DETECT_EXIT" \
+    '{status:"blocked",blocking_issue:("detect-existing.sh failed (exit " + ($exit|tostring) + ")"),before_raw:$raw}'
+  exit 1
+fi
+
+ALL_ENABLED=$(echo "$BEFORE_JSON" | jq -r '.all_enabled')
+
+# Step 2 - already fully enabled → reused (both modes)
+if [ "$ALL_ENABLED" = "true" ]; then
+  jq -n --argjson before "$BEFORE_JSON" \
+    '{status:"reused",all_enabled:true,before:$before,after:$before,deploy_id:null,safe_to_write:true,
+      manual_actions:[{id:"login_behavior",title:"Omni-Channel login behavior (UI-only)",detail:"The Omni-Channel utility auto-open-on-login behavior is a UI-only setting not exposed via the Metadata API. Set it manually if desired: Setup → Omni-Channel → Omni-Channel Settings."}]}'
+  exit 0
+fi
+
+# Step 3 - plan mode never deploys
+if [ "$MODE" = "plan" ]; then
+  jq -n --argjson before "$BEFORE_JSON" \
+    '{
+      status:"action_needed",
+      all_enabled:false,
+      action_required:"One or more OmniChannelSettings toggles are disabled. Re-run in run mode to deploy.",
+      before:$before,
+      after:null,
+      deploy_id:null,
+      manual_actions:[{id:"login_behavior",title:"Omni-Channel login behavior (UI-only)",detail:"The Omni-Channel utility auto-open-on-login behavior is a UI-only setting not exposed via the Metadata API. Set it manually if desired: Setup → Omni-Channel → Omni-Channel Settings."}]
+    }'
+  exit 0
+fi
+
+# Step 4 - run mode: safe_to_write guard (settings deploy mutates the org)
+ORG_GUARD_JSON=$(sf data query --target-org "$ORG" \
+  --query "SELECT IsSandbox, TrialExpirationDate, OrganizationType FROM Organization LIMIT 1" \
+  --json 2>/dev/null) || {
+  jq -n --arg raw "$(printf '%s' "$ORG_GUARD_JSON" | head -c 300)" \
+    '{status:"blocked",blocking_issue:("Failed to query Organization for safe_to_write guard: " + $raw)}'
+  exit 1
+}
+IS_SANDBOX=$(echo "$ORG_GUARD_JSON" | jq -r '.result.records[0].IsSandbox')
+TRIAL_EXP=$(echo "$ORG_GUARD_JSON"  | jq -r '.result.records[0].TrialExpirationDate // "null"')
+ORG_TYPE=$(echo "$ORG_GUARD_JSON"   | jq -r '.result.records[0].OrganizationType')
+
+SAFE_TO_WRITE=false
+if [ "$IS_SANDBOX" = "true" ] \
+   || [ "$TRIAL_EXP" != "null" ] \
+   || [ "$ORG_TYPE" = "Developer Edition" ] \
+   || [ "$ORG_TYPE" = "Base Edition" ]; then
+  SAFE_TO_WRITE=true
+fi
+
+if [ "$SAFE_TO_WRITE" != "true" ]; then
+  jq -n --argjson before "$BEFORE_JSON" \
+    --arg is_sandbox "$IS_SANDBOX" --arg trial "$TRIAL_EXP" --arg type "$ORG_TYPE" \
+    '{
+      status:"blocked",
+      blocking_issue:("Refusing to deploy OmniChannelSettings to a real production customer org (IsSandbox=" + $is_sandbox + ", TrialExpirationDate=" + $trial + ", OrganizationType=" + $type + ")."),
+      before:$before,
+      safe_to_write:false,
+      deploy_id:null
+    }'
+  exit 1
+fi
+
+if [ ! -f "$ASSETS_DIR/sfdx-project.json" ]; then
+  echo "{\"status\":\"blocked\",\"blocking_issue\":\"Assets DX project not found at $ASSETS_DIR\"}" >&2
+  exit 1
+fi
+
+# Step 5 - deploy the canonical settings
+SETTINGS_SOURCE="$ASSETS_DIR/force-app/main/default/settings/OmniChannel.settings-meta.xml"
+DEPLOY_JSON=$(cd "$ASSETS_DIR" && sf project deploy start --target-org "$ORG" \
+  --source-dir "$SETTINGS_SOURCE" --json 2>/dev/null || true)
+
+DEPLOY_SUCCESS=$(echo "$DEPLOY_JSON" | jq -r '.result.success // false' 2>/dev/null)
+DEPLOY_STATUS=$(echo "$DEPLOY_JSON"  | jq -r '.result.status  // .status // ""' 2>/dev/null)
+DEPLOY_ID=$(echo "$DEPLOY_JSON"      | jq -r '.result.id      // ""' 2>/dev/null)
+
+if [ "$DEPLOY_SUCCESS" != "true" ] || [ "$DEPLOY_STATUS" = "SucceededPartial" ]; then
+  FAILURES=$(echo "$DEPLOY_JSON" | jq -r '.result.details.componentFailures // [] | map(.problem) | join("; ")' 2>/dev/null)
+  if [ -z "$FAILURES" ] || [ "$FAILURES" = "null" ]; then
+    FAILURES=$(echo "$DEPLOY_JSON" | jq -r '.message // .result.errorMessage // "Unknown deploy error"' 2>/dev/null)
+  fi
+  jq -n --argjson before "$BEFORE_JSON" --arg raw "$FAILURES" --arg did "$DEPLOY_ID" \
+    '{
+      status:"blocked",
+      blocking_issue:("OmniChannelSettings deploy did not fully succeed: " + $raw),
+      before:$before,
+      after:null,
+      safe_to_write:true,
+      deploy_id:(if $did == "" then null else $did end)
+    }'
+  exit 1
+fi
+
+# Step 6 - re-detect and verify all five toggles are now enabled
+AFTER_EXIT=0
+AFTER_JSON=$(bash "$DETECT_SCRIPT" "$ORG" 2>&1) || AFTER_EXIT=$?
+
+if [ "$AFTER_EXIT" -ne 0 ] || ! echo "$AFTER_JSON" | jq -e . >/dev/null 2>&1; then
+  jq -n --argjson before "$BEFORE_JSON" --arg raw "$AFTER_JSON" --arg did "$DEPLOY_ID" \
+    '{status:"blocked",blocking_issue:"Post-deploy re-detect failed",before:$before,after_raw:$raw,deploy_id:(if $did == "" then null else $did end)}'
+  exit 1
+fi
+
+AFTER_ALL=$(echo "$AFTER_JSON" | jq -r '.all_enabled')
+
+if [ "$AFTER_ALL" != "true" ]; then
+  jq -n --argjson before "$BEFORE_JSON" --argjson after "$AFTER_JSON" --arg did "$DEPLOY_ID" \
+    '{
+      status:"blocked",
+      blocking_issue:"Deploy reported success but post-verify shows not all OmniChannelSettings toggles are enabled.",
+      before:$before,
+      after:$after,
+      safe_to_write:true,
+      deploy_id:(if $did == "" then null else $did end)
+    }'
+  exit 1
+fi
+
+jq -n --argjson before "$BEFORE_JSON" --argjson after "$AFTER_JSON" --arg did "$DEPLOY_ID" \
+  '{
+    status:"configured",
+    all_enabled:true,
+    before:$before,
+    after:$after,
+    safe_to_write:true,
+    deploy_id:(if $did == "" then null else $did end),
+    manual_actions:[{id:"login_behavior",title:"Omni-Channel login behavior (UI-only)",detail:"The Omni-Channel utility auto-open-on-login behavior is a UI-only setting not exposed via the Metadata API. Set it manually if desired: Setup → Omni-Channel → Omni-Channel Settings."}]
+  }'

package/skills/service-omni-base-settings-configure/scripts/detect-existing.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# detect-existing.sh - read-only probe of OmniChannelSettings (five toggle values + all_enabled); deterministic, no side effects. Args, output, exit codes: SKILL.md.
+
+set -euo pipefail
+
+if [ $# -lt 1 ]; then
+  echo '{"error":"Missing required argument: org-alias","usage":"bash detect-existing.sh <org-alias>"}' >&2
+  exit 1
+fi
+
+ORG="$1"
+
+# Verify org is authenticated (fail fast, do not retrieve if org auth is broken)
+if ! sf org display --target-org "$ORG" --json >/dev/null 2>&1; then
+  echo "{\"error\":\"Org alias '$ORG' is not authenticated. Run: sf org login web -a $ORG -r <my-domain-url>\"}" >&2
+  exit 1
+fi
+
+# Retrieve Settings:OmniChannel into a per-invocation temp DX project.
+# Metadata retrieve is slow (~1-2 min); this is expected and unavoidable.
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+
+cat > "$WORK/sfdx-project.json" <<'EOF'
+{"packageDirectories":[{"path":"force-app","default":true}],"sourceApiVersion":"66.0"}
+EOF
+mkdir -p "$WORK/force-app/main/default"
+
+if ! (cd "$WORK" && sf project retrieve start --target-org "$ORG" --metadata "Settings:OmniChannel" --json >/dev/null 2>&1); then
+  echo "{\"error\":\"Metadata retrieve failed for Settings:OmniChannel on org '$ORG'. This is often transient (UNKNOWN_EXCEPTION) - retry once.\"}" >&2
+  exit 1
+fi
+
+SETTINGS_RELATIVE_PATH="force-app/main/default/settings/OmniChannel.settings-meta.xml"
+XML="$WORK/$SETTINGS_RELATIVE_PATH"
+if [ ! -f "$XML" ]; then
+  echo "{\"error\":\"Retrieve succeeded but expected file not found: $SETTINGS_RELATIVE_PATH. Org may not have Omni-Channel provisioned.\"}" >&2
+  exit 1
+fi
+
+# Parse each toggle from the retrieved XML; a missing element means absent (treat as false).
+parse_toggle() {
+  local name="$1"
+  local val
+  val=$(grep -oE "<${name}>(true|false)</${name}>" "$XML" | head -1 | sed -E "s|</?${name}>||g" || true)
+  if [ "$val" = "true" ]; then echo true; else echo false; fi
+}
+
+T1=$(parse_toggle enableOmniAutoLoginPrompt)
+T2=$(parse_toggle enableOmniChannel)
+T3=$(parse_toggle enableOmniSecondaryRoutingPriority)
+T4=$(parse_toggle enableOmniSkillsRouting)
+T5=$(parse_toggle enableOmniStatusCapModel)
+
+ALL=false
+if [ "$T1" = "true" ] && [ "$T2" = "true" ] && [ "$T3" = "true" ] && [ "$T4" = "true" ] && [ "$T5" = "true" ]; then
+  ALL=true
+fi
+
+cat <<EOF
+{
+  "enableOmniAutoLoginPrompt": $T1,
+  "enableOmniChannel": $T2,
+  "enableOmniSecondaryRoutingPriority": $T3,
+  "enableOmniSkillsRouting": $T4,
+  "enableOmniStatusCapModel": $T5,
+  "all_enabled": $ALL
+}
+EOF

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

@@ -0,0 +1,168 @@
+---
+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)."
+allowed-tools: Bash Read Write Edit Glob Grep AskUserQuestion TodoWrite
+metadata:
+  version: "1.0"
+  domains: ["Service"]
+  minApiVersion: "66.0"
+  relatedSkills:
+    - "platform-metadata-deploy"
+    - "service-agentforce-human-escalation-configure"
+    - "service-omni-agent-users-create"
+    - "service-omni-base-settings-configure"
+    - "service-omni-command-center-analyze"
+    - "service-omni-permission-set-assign"
+    - "service-omni-presence-status-deploy"
+    - "service-omni-presence-user-config-deploy"
+    - "service-omni-queue-deploy"
+    - "service-omni-queue-members-assign"
+    - "service-omni-queue-routing-config-deploy"
+    - "service-omni-routing-flow-deploy"
+    - "service-omni-service-channel-configure"
+    - "service-omni-sidebar-configure"
+    - "service-omni-skills-based-routing-configure"
+    - "service-omni-supervisor-config-deploy"
+    - "service-omni-supervisor-permset-assign"
+    - "service-omni-supervisor-surface-deploy"
+    - "service-omni-supervisor-users-create"
+    - "service-omni-work-skill-routing-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-setup-coordinate
+
+Align an org toward a working Omni-Channel setup: detect what already exists and create or deploy only the missing pieces, up to a routed environment with agents, queues, presence statuses, and permissions. Full create-and-bind routing (queue + `QueueRoutingConfig` + outbound routing flow) is provided for `Case` and `VoiceCall`; `Incident` and `MessagingSession` are **verified/adopted only** by this coordinator — it reports their state and reuses existing config but does not create a missing queue/QRC/flow for them (use `service-agentforce-human-escalation-configure` for a created-and-bound `MessagingSession` handoff). This is a coordinator — it sequences the child leaf skills against a canonical set of steps and performs no writes of its own. Each leaf owns one primitive; the coordinator resolves per-org IDs, passes them between leaves, and enforces a shared reuse-vs-create and safety contract. It blocks with a click-path only for prerequisites an operator must action (a missing feature license, or a target sObject that is not enabled).
+
+`python3` is listed only because the bundled contract tests (`scripts/tests/test_omni_contracts.py`) use it; running the coordinator itself needs only `jq` and `sf`.
+
+## Inputs
+
+Confirm these once, up front, before any write:
+
+- Agent count (default `3`, range `1..10`) and supervisor count (default `1`, range `1..5`).
+- Real login email (used for password-reset flows).
+- `routing_targets` (default `["Case"]`) — any subset of `Case | Incident | MessagingSession | VoiceCall`. Only `Case` and `VoiceCall` get full create-queue + QRC + routing-flow; `Incident` and `MessagingSession` are verified/adopted (report-only).
+- Service-channel strategy — reuse standard (`Cases`, `sfdc_livemessage`, default) or create a custom channel.
+- Agent/supervisor profile — the driver provisions users on the `Service Cloud User` profile by default (Omni needs a Service Cloud license). Some orgs ship that license under a differently named profile (e.g. `Service Cloud`); override via `OMNI_AGENT_PROFILE` / `OMNI_SUPERVISOR_PROFILE` without editing the script. The user-create leaves block if the named profile is absent.
+- Runtime proof (optional) — `OMNI_RUNTIME_PROOF=1` makes the routing-flow leaf fire the trigger (fail-soft); `OMNI_RUNTIME_PROOF_REQUIRED=1` makes proof blocking. QueueBased proof requires `PendingServiceRouting` or `AgentWork`. SkillsBased proof requires a `PendingServiceRouting` with at least one `SkillRequirement`, which is the acceptance signal that `WorkSkillRouting` actually ran. The throwaway record is always cleaned up.
+- Queue selection (optional) — set `OMNI_CASE_QUEUE_DEVELOPER_NAME`, `OMNI_VOICE_QUEUE_DEVELOPER_NAME`, `OMNI_INCIDENT_QUEUE_DEVELOPER_NAME`, or `OMNI_MESSAGING_QUEUE_DEVELOPER_NAME` when the target must use a specific existing or canonical queue. Without an override, each leaf uses its target-derived default.
+- Routing-config selection (optional) — set `OMNI_CASE_ROUTING_CONFIG_DEVELOPER_NAME` or `OMNI_VOICE_ROUTING_CONFIG_DEVELOPER_NAME` to select an existing QRC explicitly. When only a queue override is supplied, the coordinator first adopts that queue's linked `QueueRoutingConfig.DeveloperName`; it creates the canonical QRC only when the queue has no linked config.
+- Queue routing controls (optional) — `OMNI_QRC_PUSH_TIMEOUT` sets the agent acceptance timeout and `OMNI_QRC_CAPACITY_PERCENTAGE` selects percentage capacity (for example, `100` for a VoiceCall that consumes the agent's full capacity). The coordinator passes both values to every QRC target.
+- Routing mode — `OMNI_ROUTING_TYPE=QueueBased|SkillsBased` is optional. When all four `OMNI_WSR_ENTITY` / `OMNI_WSR_FIELD` / `OMNI_WSR_SKILL` / `OMNI_WSR_VALUE` inputs are supplied, the coordinator infers `SkillsBased`; otherwise it defaults to `QueueBased`. SkillsBased uses `OMNI_SKILL_OPTION=RunSBRRules` (the default), binds the provisioned agents to `OMNI_SBR_SKILL` (defaults to `OMNI_WSR_SKILL`), authors the WorkSkillRouting rule, and only then activates the flow. An incomplete mapping or mismatched SBR/WSR skill is rejected before any write. `OMNI_WSR_LABEL` optionally names the rule.
+- Rep-experience stages (optional, default off) — `OMNI_REP_EXPERIENCE=1` adds presence user config (decline + decline reason + ACW) and the Omni sidebar. `OMNI_CONSOLE_APP=<app DeveloperName>` targets a specific console app; empty auto-detects one.
+- Supervisor surface (always, after the config) — once `OmniSupervisorConfig` exists, the coordinator populates its standard action + tab surface (`OmniSupervisorConfigAction` / `OmniSupervisorConfigTab`) via the Data API. Just before the classic config deploy it also runs a read-only Command Center analysis that reports whether the org is on the classic surface or Command Center V2.
+- Supervisor-config selection (optional) — set `OMNI_SUPERVISOR_CONFIG_DEVELOPER_NAME` to the exact classic `OmniSupervisorConfig.DeveloperName` that both the config and surface stages must reconcile. It defaults to `Omni_Supervisor`; use the override whenever the org has multiple configs so the coordinator never guesses. `OMNI_SUPERVISOR_CONFIG_MASTER_LABEL` optionally supplies the label when creating a new selected config.
+
+Run it in plan or run mode:
+
+```bash
+bash scripts/integration-driver.sh --plan <org-alias> [agent_count] [routing_targets_csv] [supervisor_count]
+bash scripts/integration-driver.sh --run  <org-alias> [agent_count] [routing_targets_csv] [supervisor_count]
+```
+
+`--plan` is a full read-only preview: each leaf runs its own detector and reports `reused`, `action_needed`, or `blocked`; a leaf whose prerequisite is not yet in place is reported as pending work rather than probed, so a plan never shows a misleading red for a step that is simply earlier in the sequence. A clean plan (all `reused`, exit 0) means the org is already configured; any yellow (exit 2) means work remains.
+
+## Preconditions and safety
+
+- Authenticated org via `sf` CLI using the My Domain URL (not `.lightning.force.com`).
+- Service Cloud license with headroom for the agent count.
+- `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):
+
+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.
+
+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`).
+
+| # | Child skill | Role |
+|---|---|---|
+| 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 |
+| 4 | `service-omni-queue-routing-config-deploy` | Upsert the target's `QueueRoutingConfig` (e.g. `Case_Routing_Config`, `Voice_Routing_Config`) |
+| 5 | `service-omni-queue-deploy` | Discover or create (`--create-if-missing`) a `Queue` bound to the target sObject; align it to the QRC |
+| 6 | `service-omni-queue-members-assign` | Assign users to the discovered queue |
+| 6a | `service-omni-skills-based-routing-configure` | *(SkillsBased only)* Ensure the `Skill` and active agents' `SkillUser` bindings exist |
+| 6b | `service-omni-work-skill-routing-configure` | *(SkillsBased only)* Author the required field-value → Skill rule before flow activation |
+| 6c | `service-omni-routing-flow-deploy` | Deploy the record-triggered QueueBased or SkillsBased `Flow` for `Case`/`VoiceCall`; SkillsBased passes `skillOption=RunSBRRules` |
+| 7 | `service-omni-presence-status-deploy` | Deploy `Available_<sObject>` bound to the matching channel and ensure a universal `Busy` status |
+| 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 |
+| 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 |
+| 13 | `service-omni-sidebar-configure` | *(opt-in)* Set `CustomApplication.isOmniPinnedViewEnabled=true` to pin the Omni utility region on a console app |
+| — | `platform-metadata-deploy` | Underlying Metadata API deploys used by the deploy leaves |
+
+## Behavior
+
+**Reuse-vs-create contract (enforced for every entity).** Query by `DeveloperName` (or the natural key); reuse a standard record when present (`Cases`, `sfdc_livemessage`); create from the leaf's bundled definition when nothing exists; reconcile idempotently when a same-named custom record exists — never duplicate, rename, or mutate the identity of a standard or managed record.
+
+**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.
+
+**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.
+
+**Login-behavior gap.** The login-behavior radio (Setup → Omni-Channel Settings → "Define login behavior when an agent opens a new window/tab") has no public API on v66. After base settings deploy, the coordinator surfaces the exact click-path; it does not attempt to flip it via `enableOmniAutoLoginPrompt`, which deploys but does not drive the radio. See `references/gap-catalog.md`.
+
+**Credentials.** Generated passwords are moved into a single restricted `CREDENTIALS.json` (mode 0600) and redacted from every other artifact. The write is atomic and fail-closed: on any redaction or verification failure the plaintext artifact is removed and the run aborts, so no plaintext password is left in the artifacts directory. The operator reads `CREDENTIALS.json` once, distributes securely, then deletes it.
+
+## Output contract
+
+The one deliverable is a single report file. As the final action you MUST use the `Write` tool to save the complete report to `omni-coordinate-report.md` in the current working directory — never deliver it only in chat. In `--run` mode it states what *is* (created resource, reused standard record, resolved decision) — no hedging. In `--plan` mode it states each leaf's honest disposition (`reused` / `action_needed` / pending) plus the coordinator's plan JSON (`dry_run: true`). Each leaf also writes its full JSON outcome (including every created record Id and deploy Id) to a per-skill artifact under the run's artifacts directory — that is the audit trail; user-facing output uses human-readable names, not record Ids. See `examples/output-templates.md` for the report shape.
+
+**Run artifacts (run mode).** Alongside the per-skill artifacts, a `--run` writes three files into the run's artifacts directory (paths echoed in the report JSON as `run_log`, `deploy_ids_file`, `teardown_script`): `run.log` (sanitized, human-readable step sequence and result), `deploy_ids.json` (a provenance manifest — each entry's `provenance` is `created` / `updated` / `reused`, with resource ids, a `before` snapshot, and a pointer to the authoritative per-skill artifact), and `teardown.sh` (an auto-generated, **dry-run** reverse-dependency-order plan). The teardown script prints what a teardown would `REMOVE` (run-created), `RESTORE` (updated, with prior values), or `KEEP` (adopted/reused — never deleted) and makes no changes; destructive execution stays manual by design (see Limitations).
+
+Report content rules:
+
+- Report concrete outcomes, never intentions.
+- Surface the login-behavior click-path whenever setup ran, even if the operator declined to turn the radio.
+- Surface any hard fail from step 5 (no queue bound) as a manual action with a click-path.
+
+## 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.
+- 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. |
+
+## References
+
+| File | When to read |
+|---|---|
+| `references/gap-catalog.md` | The headless gaps (login-behavior radio, Agentforce routing target, Field Service skills routing) and how the coordinator handles each |
+| `examples/output-templates.md` | Before emitting the report — canonical Setup Summary, Skill Outcomes, and Manual Actions blocks |

package/skills/service-omni-channel-setup-coordinate/examples/output-templates.md

@@ -0,0 +1,161 @@
+# Report templates
+
+Read this reference before emitting the final report. Every coordinator run produces exactly one user-facing artifact: `report.md`. This file defines its structure so every run's report is consistent and easy to read.
+
+**Rule:** report concrete outcomes only. No hedges ("will create", "to be resolved", "pending confirmation"), no padding — dense, declarative lines.
+
+The coordinator runs a dependency-ordered setup of the child skills (see `SKILL.md` → *Skills this coordinates*). The report is a **Skill Outcomes** table. Each skill's status is one of `Done` (created/updated/deployed/configured/bound/assigned), `Reused`, `Skipped`, `Blocked`, or `Blocked (dependency)` — the last is emitted when a prerequisite skill went red and the dependent skill was intentionally not run.
+
+**Credentials never appear in `report.md`.** Generated passwords are written once to a restricted `CREDENTIALS.json` (mode 0600) and redacted from every other artifact. The report points the operator at that file; it never prints a plaintext password.
+
+---
+
+## Template A — Full run (happy path)
+
+Use when every skill completed successfully (or was correctly reused/skipped for idempotency).
+
+```markdown
+# Omni-Channel Setup Report (via service-omni-channel-setup-coordinate)
+
+## Setup Summary
+| Field | Value |
+|---|---|
+| Org | mytestorg (Sandbox) |
+| Agents / Supervisors provisioned | 5 / 1 |
+| Routing targets | Case, MessagingSession |
+| Service Channel strategy | Reused standard: Cases, sfdc_livemessage |
+
+## Skill Outcomes
+| # | Skill | Target(s) | Status | Notes |
+|---|---|---|---|---|
+| 1 | base-settings-configure | — | Reused | All 5 OmniChannel toggles already enabled |
+| 2 | agent-users-create | — | Done | 5 agent users created |
+| 3 | service-channel-configure | Case, MessagingSession | Reused | Standard Cases + sfdc_livemessage channels |
+| 4 | queue-routing-config-deploy | Case | Done | Case_Routing_Config upserted (MostAvailable, weight 5) |
+| 5 | queue-deploy | Case, MessagingSession | Done | Case queue aligned to Case_Routing_Config; messaging queue reused |
+| 6 | queue-members-assign | Case, MessagingSession | Done | 5 agents bound to each target queue |
+| 7 | routing-flow-deploy | Case | Done | Case routing flow deployed and active |
+| 8 | presence-status-deploy | Case, MessagingSession | Done | Available_Case + Available_Messaging bound; Busy universal (reused) |
+| 9 | permission-set-assign | — | Done | Omni_Agent assigned to 5 agents |
+| 10 | supervisor-users-create | — | Done | 1 supervisor user created |
+| 11 | supervisor-permset-assign | — | Done | ContactCenterSupervisor assigned to 1 supervisor |
+| 12 | supervisor-config-deploy | — | Done | Omni_SupervisorCfg bound 1 supervisor + 2 discovered queues |
+
+## Manual Actions Required
+- **Login-behavior radio** — open Setup → Omni-Channel Settings → "Define login behavior when an agent opens a new window/tab" → select the desired option → Save. The `enableOmniAutoLoginPrompt` boolean deploys but does not drive this radio on v66.
+
+## Artifacts
+- `CREDENTIALS.json` (mode 0600) — generated agent + supervisor passwords. Read once, distribute securely, then delete (`rm -f`). Passwords are redacted from all other artifacts.
+- Per-skill JSON artifacts + `.stderr.log` under the run's artifacts directory.
+
+## Blocking Issues
+None.
+
+## Next Action
+Read `CREDENTIALS.json` for the agent login, then log in, open the Service Console, click the Omni-Channel widget, set status to Online, and create a Case with Priority=Medium to observe routing.
+```
+
+---
+
+## Template B — Partial run (a skill went red; dependents skipped)
+
+Use when a prerequisite skill failed and the coordinator correctly skipped its dependents as `Blocked (dependency)`. The overall run is `red`; the report names the single blocker.
+
+```markdown
+# Omni-Channel Setup Report (via service-omni-channel-setup-coordinate)
+
+## Setup Summary
+| Field | Value |
+|---|---|
+| Org | mytestorg (CDO) |
+| Agents / Supervisors provisioned | 5 / 1 |
+| Routing targets | Case |
+| Service Channel strategy | Reused standard: Cases |
+
+## Skill Outcomes
+| # | Skill | Target(s) | Status | Notes |
+|---|---|---|---|---|
+| 1 | base-settings-configure | — | Blocked | Deploy returned SucceededPartial; OmniChannel toggle did not stick |
+| 2 | agent-users-create | — | Done | 5 agent users created |
+| 3 | service-channel-configure | Case | Blocked (dependency) | base-settings did not succeed |
+| 4 | queue-routing-config-deploy | Case | Blocked (dependency) | base-settings did not succeed |
+| 5 | queue-deploy | Case | Blocked (dependency) | base-settings did not succeed |
+| 6 | queue-members-assign | Case | Blocked (dependency) | queue-deploy did not succeed |
+| 7 | routing-flow-deploy | Case | Blocked (dependency) | queue-members did not succeed |
+| 8 | presence-status-deploy | Case | Blocked (dependency) | base-settings did not succeed |
+| 9 | permission-set-assign | — | Done | Omni_Agent assigned to 5 agents |
+| 10 | supervisor-users-create | — | Done | 1 supervisor user created |
+| 11 | supervisor-permset-assign | — | Done | ContactCenterSupervisor assigned to 1 supervisor |
+| 12 | supervisor-config-deploy | — | Blocked (dependency) | base-settings did not succeed |
+
+## Manual Actions Required
+- **Login-behavior radio** — (as in Template A)
+
+## Artifacts
+- `CREDENTIALS.json` (mode 0600) — generated agent + supervisor passwords. Read once, distribute securely, then delete.
+- Per-skill JSON artifacts + `.stderr.log` under the run's artifacts directory.
+
+## Blocking Issues
+base-settings-configure returned SucceededPartial and the OmniChannel toggle did not persist on re-verify — every skill that requires Omni enabled was skipped as a dependency block.
+
+## Next Action
+Inspect the base-settings deploy for the org, resolve the partial-deploy failure, then re-invoke the coordinator (idempotent — completed skills are reused).
+```
+
+---
+
+## Template C — Hard-stop before setup
+
+Use when the readiness check failed and no writes were made — e.g. license shortfall, missing entity, production org without acknowledgement.
+
+Fill **only** Setup Summary and Blocking Issues. Mark every skill row `Not started`. Point Next Action at the one thing that unblocks the run.
+
+```markdown
+# Omni-Channel Setup Report (via service-omni-channel-setup-coordinate)
+
+## Setup Summary
+| Field | Value |
+|---|---|
+| Org | mytestorg (Production) |
+| Agents / Supervisors requested | 5 / 1 |
+| Routing targets | Case |
+
+## Skill Outcomes
+| # | Skill | Status |
+|---|---|---|
+| 1–12 | all skills | Not started — blocked at readiness check |
+
+## Blocking Issues
+Target org is Production (IsSandbox=false, no TrialExpirationDate, OrganizationType=Enterprise Edition). safe_to_write=false; the coordinator refuses writes against production customer orgs.
+
+## Next Action
+Switch to a sandbox, CDO (trial), or Developer Edition alias and re-invoke.
+```
+
+---
+
+## Report-quality checklist
+
+Before emitting, mentally verify:
+
+- [ ] Header ends with `(via service-omni-channel-setup-coordinate)`
+- [ ] Every skill row's `Status` reflects the tracked state — not a hard-coded default
+- [ ] A dependent skill whose prerequisite went red is shown as `Blocked (dependency)`, never `Done`
+- [ ] The login-behavior click-path is surfaced whenever setup ran (even if the operator declines to turn the radio)
+- [ ] **No plaintext passwords appear in the report** — they live only in `CREDENTIALS.json` (mode 0600); the report points the operator there
+- [ ] **No Salesforce record IDs appear in the user-facing report** — human-readable names only
+- [ ] A production org (`IsSandbox=false`, no `TrialExpirationDate`, non-DE/Base) was refused before setup started
+- [ ] `Blocking Issues` is either `None.` or exactly one blocker (the coordinator should not chain multiple issues)
+- [ ] `Next Action` is exactly one line — the single next step
+
+---
+
+## Anti-patterns to avoid
+
+- AVOID: "Will create Omni_Demo_Cases_Queue" — say `Done` and list what was created, not what you plan to do
+- AVOID: "Attempting to configure supervisor..." — the report emits after the action; describe the outcome, not the attempt
+- AVOID: A plaintext password in `Next Action` or anywhere else in the report — point at `CREDENTIALS.json` instead
+- AVOID: Salesforce record IDs in Skill Outcomes notes — human-readable DeveloperNames only, never `0C5RZ0000001I1J0AU`
+- AVOID: Multi-line Blocking Issues — collapse to one line; if multiple issues, the coordinator should have stopped after the first
+- AVOID: Preamble ("Here is the report you requested...") — jump straight to `# Omni-Channel Setup Report`
+- AVOID: Design-doc padding ("The coordinator orchestrates multiple skills...") — the report is a status log, not a spec