@salesforce/afv-skills 1.46.0 → 1.48.0

package/skills/service-native-voice-recording-transcription-configure/SKILL.md

@@ -1,10 +1,13 @@
 ---
 name: service-native-voice-recording-transcription-configure
-description: "Enable call recording and call transcription for Native Voice (Thunderbird Voice) programmatically via the Metadata API, for headless / API-driven support where no human uses the Service Console UI. Use this skill when a user asks to turn on, enable, or configure Native Voice recording and/or transcription for headless or automated voice calls. TRIGGER when: users mention Thunderbird Voice, Native Voice, ThunderbirdVoiceSettings, enableCallRecording, enableCallTranscription, 'enable recording and transcription', 'turn on call recording via API', headless voice recording, or configuring voice-call capture without clicking through Setup. DO NOT TRIGGER when: the user wants to redact or scrub PII from existing recordings, transcribe a supplied audio file, or author a Flow/Apex — those are out of scope for this skill."
+description: "Configure (enable OR disable) call recording and call transcription for Native Voice (Thunderbird Voice) programmatically via the Metadata API, for headless / API-driven support where no human uses the Service Console UI. Either preference can be turned on or off independently. Use this skill when a user asks to turn on/off, enable/disable, or configure Native Voice recording and/or transcription for headless or automated voice calls. TRIGGER when: users mention Thunderbird Voice, Native Voice, ThunderbirdVoiceSettings, enableCallRecording, enableCallTranscription, 'enable recording and transcription', 'turn off call recording', 'disable transcription', 'turn on call recording via API', headless voice recording, or configuring voice-call capture without clicking through Setup. DO NOT TRIGGER when: the user wants to redact or scrub PII from existing recordings, transcribe a supplied audio file, or author a Flow/Apex — those are out of scope for this skill."
 metadata:
-  version: "1.1"
+  version: "1.2"
   domains: ["Service"]
   minApiVersion: "68.0"
+  accessCheck:
+    - type: "orgPerm"
+      value: "ThunderbirdVoice.orgHasNativeVoiceAllowed"
   cliTools:
     - tool: ["jq"]
       semver: ">=1.6"
@@ -12,20 +15,23 @@ metadata:
       semver: ">=2.0.0"
 ---
 
-# Enable Native Voice Recording & Transcription (headless)
+# Configure Native Voice Recording & Transcription (headless)
 
-Turn on call **recording** and call **transcription** for Native Voice (Thunderbird
-Voice) on an org, programmatically, so they take effect for headless / API-driven
-support sessions that never touch the Service Console UI. Recording and transcription
-are **two separate preferences** — this skill enables both and returns a structured
-JSON confirmation.
+Turn call **recording** and call **transcription** for Native Voice (Thunderbird
+Voice) **on or off** on an org, programmatically, so the change takes effect for
+headless / API-driven support sessions that never touch the Service Console UI.
+Recording and transcription are **two separate preferences** — this skill can set
+either or both to the requested state (leaving the other untouched) and returns a
+structured JSON confirmation.
 
 ## Scope
 
-- **In scope**: enabling `enableCallRecording` and `enableCallTranscription` on the
+- **In scope**: setting `enableCallRecording` and/or `enableCallTranscription` to a
+  requested state — **`true` (enable) or `false` (disable)** — on the
   `ThunderbirdVoiceSettings` metadata via an sf CLI Metadata API deploy (the generic
   `Settings` container, member `ThunderbirdVoice`); returning a JSON confirmation of
-  the resulting configuration.
+  the resulting configuration. A preference the user does not name is left at its
+  current value.
 - **Out of scope**: changing any other `ThunderbirdVoiceSettings` boolean (e.g.
   call-recording redaction, SIP recording) — siblings are read only to be preserved,
   never set or reported; redacting/scrubbing PII from existing recordings or
@@ -43,8 +49,11 @@ Gather or infer before proceeding:
   uses this existing `sf` login; no session id or access token is requested. Default:
   the org's default target. Confirm connectivity with `sf org display -o <alias>`.
 - **Which preferences** — recording, transcription, or both. Default: **both**, since
-  headless capture typically needs recording *and* transcription. Confirm only if the
-  user named just one.
+  headless capture typically needs recording *and* transcription. If the user named
+  just one, target only that one and leave the other at its current value.
+- **Desired state** — enable (`on`/`true`) or disable (`off`/`false`) for each named
+  preference. Default: **enable**, unless the user asks to turn something off. Honor a
+  disable request literally — never re-enable a preference the user asked to turn off.
 
 ---
 
@@ -58,13 +67,18 @@ missing org context.
    booleans on the same metadata type — never collapse them into one combined flag.
    The final confirmation must report each independently.
 
-2. **Run the enable script.** Run
-   `scripts/enable-recording-transcription.sh --target-org <alias>`. It retrieves
-   `ThunderbirdVoiceSettings` (via the `Settings` container), checks the org-perm gate,
-   flips the two target flags to `true` while preserving every sibling, validates with
-   a dry-run deploy, deploys, and verifies by round-trip. Use `--dry-run` to retrieve +
-   validate without persisting. Run
-   `scripts/enable-recording-transcription.sh --help` for all options.
+2. **Run the configure script.** Run
+   `scripts/enable-recording-transcription.sh --target-org <alias>` with the desired
+   state per preference: `--recording on|off` and/or `--transcription on|off`. With no
+   preference flags it defaults to turning **both on**. Examples: turn both off →
+   `--recording off --transcription off`; enable recording only →
+   `--recording on` (transcription left as-is); disable transcription only →
+   `--transcription off`. The script retrieves `ThunderbirdVoiceSettings` (via the
+   `Settings` container), checks the org-perm gate, sets **only the named** flag(s) to
+   the requested value while preserving every other field, validates with a dry-run
+   deploy, deploys, and verifies by round-trip. Use `--dry-run` to retrieve + validate
+   without persisting. Run `scripts/enable-recording-transcription.sh --help` for all
+   options.
 
 3. **For the Metadata API contract**, read `references/thunderbird-voice-settings.md` —
    it documents the type, the two booleans, the `Settings`-container manifest, the
@@ -75,15 +89,20 @@ missing org context.
    > mdApiType **without** the `Settings` suffix (`ThunderbirdVoice`), and the manifest
    > version MUST be **>= 68.0** — the fields are not exposed at any lower version.
 
-4. **Change only the two target fields.** The deployed settings file sets exactly
-   `enableCallRecording` and `enableCallTranscription` to `true`; every other
-   `ThunderbirdVoiceSettings` boolean keeps its retrieved value. Do not add or flip
-   other booleans — they are out of this skill's scope.
+4. **Change only the named target field(s), to the requested state.** The deployed
+   settings file sets exactly the preference(s) the user named — `enableCallRecording`
+   and/or `enableCallTranscription` — to the requested value (`true` to enable, `false`
+   to disable); every other `ThunderbirdVoiceSettings` boolean, INCLUDING a target
+   preference the user did not name, keeps its retrieved value. Do not add or flip
+   other booleans, and never coerce a disable request back to `true` — they are out of
+   this skill's scope or contrary to the request.
 
 5. **Return the confirmation JSON.** Emit a single JSON object matching
    `assets/confirmation-output.json`: the metadata `type` and `fullName`, that it was
    applied via a headless/API deploy, and — for **each** of the two preferences
-   separately — its field name and enabled state, plus an overall `status`. It also
+   separately — its field name and its resulting enabled state (`true`/`false`, as it
+   now stands after the deploy, whether it was changed or left as-is), plus an overall
+   `status` (`ENABLED`, `DISABLED`, or `CONFIGURED`). It also
    includes a **`preserved`** array echoing every sibling boolean (e.g.
    `enableCallRecRedaction`, `enableSipRecording`) with the value it was retrieved
    with — this attests the siblings were carried through **unchanged**, which
@@ -102,8 +121,9 @@ missing org context.
 | Deploy through the generic `Settings` container with member `ThunderbirdVoice` | `ThunderbirdVoiceSettings` is not a retrievable top-level type name; the `Settings` container (member = mdApiType minus the `Settings` suffix) is the sf CLI path and uses the org's `sf` login — no session id. |
 | Manifest version must be >= 68.0 | `ThunderbirdVoiceSettings` fields are only exposed at API v68.0+; below that the retrieve returns the type empty/absent. |
 | Retrieve before deploy; preserve all sibling fields | The deploy is a full-file replace — starting from the retrieved file keeps other prefs intact and lets the gate be checked. |
-| Report the preserved siblings in a `preserved` block, but never change them | Compliance callers need explicit "nothing else moved" assurance; the confirmation echoes each sibling's retrieved value unchanged. Echoing a value is not setting it — the deployed file still flips only the two target fields. |
-| Verify by round-trip before reporting `ENABLED` | A "Succeeded" deploy is not proof; only claim enabled after a re-retrieve returns both `true`. |
+| Report the preserved siblings in a `preserved` block, but never change them | Compliance callers need explicit "nothing else moved" assurance; the confirmation echoes each sibling's retrieved value unchanged. Echoing a value is not setting it — the deployed file changes only the named target field(s). |
+| Honor the requested state literally — enable means `true`, disable means `false` | A disable request that silently re-enables the preference (or reports success while leaving it on) is a correctness failure; set exactly what was asked and report the value the org actually returns. |
+| Verify by round-trip before reporting the status | A "Succeeded" deploy is not proof; only report the resulting state after a re-retrieve returns each named preference at its requested value. |
 | Output must be a single valid JSON object | The confirmation is consumed programmatically by headless callers; prose-only answers are not usable. |
 | Do not include a session id, access token, phone number, recording URL, or transcript content in the output | These are secrets / PII; the confirmation reports configuration state only. |
 
@@ -140,7 +160,7 @@ project and reports the result.
 
 | File | When to read |
 |------|-------------|
-| `scripts/enable-recording-transcription.sh` | Step 2 — run to retrieve → flip → validate → deploy → verify (supports `--dry-run`, `--api-version`, `--help`). |
+| `scripts/enable-recording-transcription.sh` | Step 2 — run to retrieve → set named field(s) → validate → deploy → verify (supports `--recording on\|off`, `--transcription on\|off`, `--dry-run`, `--api-version`, `--help`; defaults to both on). |
 | `references/thunderbird-voice-settings.md` | Step 3 — for the metadata type, the two booleans, the `Settings` manifest, the v68.0+ floor, and the gate check. |
 | `assets/package.xml` | Step 3 — the Metadata API manifest template the script generates; read to understand or hand-build the retrieve/deploy. |
 | `assets/confirmation-output.json` | Step 5 — the exact shape of the JSON confirmation to return. |

package/skills/service-native-voice-recording-transcription-configure/references/thunderbird-voice-settings.md

@@ -1,8 +1,9 @@
 # ThunderbirdVoiceSettings — Metadata API contract
 
-Reference for enabling Native Voice (Thunderbird Voice) recording and transcription
-via the Metadata API, using the sf CLI `Settings`-container retrieve/deploy path.
-Read this when constructing or debugging `scripts/enable-recording-transcription.sh`.
+Reference for configuring — enabling **or disabling** — Native Voice (Thunderbird
+Voice) recording and transcription via the Metadata API, using the sf CLI
+`Settings`-container retrieve/deploy path. Read this when constructing or debugging
+`scripts/enable-recording-transcription.sh`.
 
 ## The metadata type
 
@@ -16,12 +17,13 @@ This skill manages exactly two boolean preferences:
 
 | Field | Meaning | This skill |
 |-------|---------|------------|
-| `enableCallRecording` | Capture audio of Native Voice calls | **set `true`** (target) |
-| `enableCallTranscription` | Produce transcripts of Native Voice calls | **set `true`** (target) |
+| `enableCallRecording` | Capture audio of Native Voice calls | **set to the requested state** (`true`/`false`) when named (target) |
+| `enableCallTranscription` | Produce transcripts of Native Voice calls | **set to the requested state** (`true`/`false`) when named (target) |
 
 Recording and transcription are independent — a call can be recorded without being
 transcribed and vice versa — so they are always modeled and reported as two separate
-preferences.
+preferences, and each can be enabled or disabled on its own. A target preference the
+caller does not name is left at its retrieved value, exactly like a sibling.
 
 The type may expose other booleans (e.g. `enableCallRecRedaction`,
 `enableRealTimeStreamingRecording`, `enableSipRecording`). They are **out of scope** to
@@ -74,11 +76,13 @@ SFDX project). Two things matter:
    (no fields), the org-perm gate `ThunderbirdVoice.orgHasNativeVoiceAllowed` is **off**
    — Native Voice is not provisioned. Stop; this is enabled via provisioning/Blacktab,
    not this skill. If the fields are listed, the gate is on — proceed.
-3. **Flip** `enableCallRecording` and `enableCallTranscription` to `true`; leave every
-   sibling field at its retrieved value.
+3. **Set** each named target (`enableCallRecording` and/or `enableCallTranscription`)
+   to its requested value (`true` to enable, `false` to disable); leave every other
+   field — siblings and any un-named target — at its retrieved value.
 4. **Validate** with `deploy --dry-run` (never skip).
 5. **Deploy**.
-6. **Verify** by re-retrieving and confirming the org *returns* both `true`.
+6. **Verify** by re-retrieving and confirming the org *returns* each named field at
+   its requested value.
 
 ## Distinguishing the two failure modes
 

package/skills/service-native-voice-recording-transcription-configure/scripts/enable-recording-transcription.sh

@@ -1,27 +1,35 @@
 #!/usr/bin/env bash
 #
-# Enable Native Voice (Thunderbird Voice) call recording + transcription via the
-# Metadata API, using the sf CLI Settings-container retrieve/deploy path.
+# Configure Native Voice (Thunderbird Voice) call recording + transcription via
+# the Metadata API, using the sf CLI Settings-container retrieve/deploy path.
 #
-# Scope: this skill enables exactly two preferences — enableCallRecording and
-# enableCallTranscription. Every other ThunderbirdVoiceSettings boolean is read
-# only to be preserved verbatim — none is changed. The siblings ARE reported
-# back (unchanged) in a `preserved` block so compliance callers can confirm
-# nothing else moved; reporting a value is not the same as setting it.
+# Scope: this skill configures exactly two preferences — enableCallRecording and
+# enableCallTranscription — to a requested ON or OFF state. Either or both may be
+# targeted (`--recording on|off`, `--transcription on|off`); a preference that is
+# NOT named is left at its retrieved value (preserved), so you can turn one on or
+# off without disturbing the other. With NO preference flags the script defaults
+# to turning BOTH on (the original enable-both behavior). Every OTHER
+# ThunderbirdVoiceSettings boolean is read only to be preserved verbatim — none
+# is changed. The siblings ARE reported back (unchanged) in a `preserved` block
+# so compliance callers can confirm nothing else moved; reporting a value is not
+# the same as setting it.
 #
 # Why sf CLI (not raw SOAP): the generic `Settings` metadata type IS in the sf
 # CLI registry (member = the type name without the `Settings` suffix, i.e.
 # `ThunderbirdVoice`). Deploying through it authenticates with the org's existing
 # `sf` login — no browser session id / access token is ever handled. Retrieving
-# first lets us (a) check the org-perm gate and (b) preserve sibling prefs.
+# first lets us (a) check the org-perm gate and (b) preserve non-targeted prefs.
 #
-# Sequence: retrieve -> gate check -> flip the two target fields -> validate
-# (dry-run) -> deploy -> verify by round-trip -> print a JSON confirmation.
+# Sequence: retrieve -> gate check -> set the targeted field(s) to the requested
+# state -> validate (dry-run) -> deploy -> verify by round-trip -> print a JSON
+# confirmation reporting the resulting state of BOTH preferences.
 #
 # Deps: sf, jq. (No curl, no session id.)
 #
 set -euo pipefail
 
+fail() { echo "ERROR: $*" >&2; exit 1; }
+
 # ThunderbirdVoiceSettings fields are only exposed at API v68.0+; below that the
 # Settings type does not appear in a retrieve at all. Default to exactly 68.0 — the
 # field-exposure floor. A retrieve/deploy at a version ABOVE the org's max supported
@@ -31,6 +39,9 @@ set -euo pipefail
 API_VERSION="68.0"
 TARGET_ORG=""
 DRY_RUN="false"
+# Desired state per target field: "" = not targeted (preserve), else "true"/"false".
+REC_STATE=""
+TRANS_STATE=""
 
 # mdApiType ThunderbirdVoiceSettings -> package.xml member without the "Settings" suffix.
 MEMBER="ThunderbirdVoice"
@@ -38,39 +49,60 @@ SETTINGS_FILE_REL="force-app/main/default/settings/${MEMBER}.settings-meta.xml"
 
 usage() {
   cat <<'EOF'
-Enable Native Voice call recording + transcription (sf CLI Settings deploy).
+Configure Native Voice call recording + transcription (sf CLI Settings deploy).
 
 Usage:
-  enable-recording-transcription.sh --target-org <alias> [--dry-run] [--api-version X.Y]
+  enable-recording-transcription.sh --target-org <alias> \
+      [--recording on|off] [--transcription on|off] [--dry-run] [--api-version X.Y]
 
 Options:
-  --target-org <alias>   Org alias/username the sf CLI is authenticated to. Required.
-  --api-version <X.Y>    Metadata API version (default: 68.0; must be >= 68.0, the
-                         version at which ThunderbirdVoiceSettings is exposed). Do NOT
-                         exceed the target org's max supported version — a retrieve
-                         above it silently returns empty.
-  --dry-run              Retrieve + validate the change (deploy --dry-run) but do NOT
-                         persist it. Prints the JSON confirmation with status VALIDATED.
-  -h, --help             Show this help.
-
-On success prints a JSON confirmation object: the two enabled preferences reported
-separately, plus a `preserved` block echoing every sibling boolean (unchanged) so
-callers can confirm nothing else moved.
+  --target-org <alias>     Org alias/username the sf CLI is authenticated to. Required.
+  --recording on|off       Desired state for call recording (enableCallRecording).
+  --transcription on|off   Desired state for call transcription (enableCallTranscription).
+                           If NEITHER --recording nor --transcription is given, the
+                           script defaults to turning BOTH on. A preference that is
+                           not named is left at its current (retrieved) value.
+  --api-version <X.Y>      Metadata API version (default: 68.0; must be >= 68.0, the
+                           version at which ThunderbirdVoiceSettings is exposed). Do NOT
+                           exceed the target org's max supported version — a retrieve
+                           above it silently returns empty.
+  --dry-run                Retrieve + validate the change (deploy --dry-run) but do NOT
+                           persist it. Prints the JSON confirmation with status VALIDATED.
+  -h, --help               Show this help.
+
+On success prints a JSON confirmation object: BOTH preferences reported separately
+with their resulting state, plus a `preserved` block echoing every sibling boolean
+(unchanged) so callers can confirm nothing else moved.
 Uses the org's sf login; no session id / access token is handled or printed.
 EOF
 }
 
+# Normalize an on/off style value to the literal "true"/"false" used in the XML.
+onoff() { # $1 = flag name (for errors), $2 = value
+  case "$2" in
+    on|true|enable|enabled)     echo "true" ;;
+    off|false|disable|disabled) echo "false" ;;
+    *) fail "invalid value for $1: '$2' (expected on|off)." ;;
+  esac
+}
+
 while [ $# -gt 0 ]; do
   case "$1" in
     --target-org) TARGET_ORG="$2"; shift 2 ;;
     --api-version) API_VERSION="$2"; shift 2 ;;
+    --recording) REC_STATE="$(onoff --recording "$2")"; shift 2 ;;
+    --transcription) TRANS_STATE="$(onoff --transcription "$2")"; shift 2 ;;
     --dry-run) DRY_RUN="true"; shift ;;
     -h|--help) usage; exit 0 ;;
     *) echo "ERROR: unknown argument: $1" >&2; usage >&2; exit 2 ;;
   esac
 done
 
-fail() { echo "ERROR: $*" >&2; exit 1; }
+# Default: if neither preference was named, target BOTH on — the original
+# enable-both behavior, so existing callers keep working unchanged.
+if [ -z "$REC_STATE" ] && [ -z "$TRANS_STATE" ]; then
+  REC_STATE="true"; TRANS_STATE="true"
+fi
 
 command -v sf  >/dev/null 2>&1 || fail "sf CLI not found (required)."
 command -v jq  >/dev/null 2>&1 || fail "jq not found (required)."
@@ -100,6 +132,15 @@ EOF
 
 SETTINGS_FILE="$PROJ/$SETTINGS_FILE_REL"
 
+# Read the literal true/false a boolean field currently holds in the settings
+# file; echoes "false" if the field is absent (guarded so an empty grep under
+# `set -o pipefail` does not abort the script).
+read_pref() { # $1 = settings xml file, $2 = field name
+  local v
+  v="$({ grep -oE "<$2>(true|false)</$2>" "$1" || true; } | sed -E "s#<$2>([a-z]+)</$2>#\1#" | head -n1)"
+  echo "${v:-false}"
+}
+
 # --- step 1: retrieve current settings (gate check + sibling snapshot) --------
 ( cd "$PROJ" && sf project retrieve start -x package.xml -o "$TARGET_ORG" >/dev/null 2>&1 ) \
   || fail "retrieve failed for org '$TARGET_ORG'. Check the alias is connected (sf org display -o $TARGET_ORG)."
@@ -113,24 +154,27 @@ if ! grep -q '<enableCallRecording>' "$SETTINGS_FILE"; then
   fail "Native Voice is not provisioned on '$TARGET_ORG' (ThunderbirdVoiceSettings returned no fields). This is an org-perm gate enabled through provisioning/Blacktab, not something this skill can flip."
 fi
 
-# --- step 2: flip only the two target fields, preserve every sibling ----------
-# Version-suffixed sed -i for BSD (macOS) + GNU portability.
-sed -E -i.bak \
-  -e 's|<enableCallRecording>[^<]*</enableCallRecording>|<enableCallRecording>true</enableCallRecording>|' \
-  -e 's|<enableCallTranscription>[^<]*</enableCallTranscription>|<enableCallTranscription>true</enableCallTranscription>|' \
-  "$SETTINGS_FILE"
+# --- step 2: set ONLY the targeted field(s) to the requested state ------------
+# A field that is not targeted is left at its retrieved value (preserved), just
+# like the siblings. Version-suffixed sed -i for BSD (macOS) + GNU portability.
+SED_ARGS=()
+[ -n "$REC_STATE" ]   && SED_ARGS+=(-e "s|<enableCallRecording>[^<]*</enableCallRecording>|<enableCallRecording>${REC_STATE}</enableCallRecording>|")
+[ -n "$TRANS_STATE" ] && SED_ARGS+=(-e "s|<enableCallTranscription>[^<]*</enableCallTranscription>|<enableCallTranscription>${TRANS_STATE}</enableCallTranscription>|")
+sed -E -i.bak "${SED_ARGS[@]}" "$SETTINGS_FILE"
 rm -f "${SETTINGS_FILE}.bak"
 
-grep -q '<enableCallRecording>true</enableCallRecording>'     "$SETTINGS_FILE" || fail "could not set enableCallRecording in the retrieved file."
-grep -q '<enableCallTranscription>true</enableCallTranscription>' "$SETTINGS_FILE" || fail "could not set enableCallTranscription in the retrieved file."
+# A targeted field must now hold the requested value; if the tag was absent the
+# sed matched nothing (a provisioned org exposes both, so this is an edge case).
+[ -z "$REC_STATE" ]   || grep -q "<enableCallRecording>${REC_STATE}</enableCallRecording>"     "$SETTINGS_FILE" || fail "could not set enableCallRecording=${REC_STATE} in the retrieved file (field absent?)."
+[ -z "$TRANS_STATE" ] || grep -q "<enableCallTranscription>${TRANS_STATE}</enableCallTranscription>" "$SETTINGS_FILE" || fail "could not set enableCallTranscription=${TRANS_STATE} in the retrieved file (field absent?)."
 
 # --- step 3: validate (dry-run). Never skip. ---------------------------------
 ( cd "$PROJ" && sf project deploy start -x package.xml -o "$TARGET_ORG" --dry-run --ignore-conflicts >/dev/null 2>&1 ) \
   || fail "validation (deploy --dry-run) failed — the org rejected the change. Re-check the gate (step 1)."
 
 # Collect every boolean sibling (<tag>true|false</tag>) EXCEPT the two target
-# prefs from the retrieved settings file, as a JSON array [{name, enabled}], so
-# the confirmation can attest each sibling was retrieved and carried through
+# prefs from the settings file, as a JSON array [{name, enabled}], so the
+# confirmation can attest each sibling was retrieved and carried through
 # unchanged. `grep -o` isolates each pair; `#`-delimited sed avoids colliding
 # with the `|` alternation; the `|| true` guards keep an empty result (no
 # siblings) from tripping `set -o pipefail`.
@@ -141,8 +185,16 @@ extract_preserved() { # $1 = settings xml file -> JSON array on stdout
     | jq -R -s 'split("\n") | map(select(length > 0) | split(" ") | { name: .[0], enabled: (.[1] == "true") })'
 }
 
-emit_json() { # $1 = status, $2 = preserved siblings JSON array
-  jq -n --arg apiVersion "$API_VERSION" --arg status "$1" --argjson preserved "$2" \
+# Overall status word from the resulting state of the two target preferences.
+compute_status() { # $1 = recording bool, $2 = transcription bool
+  if   [ "$1" = "true"  ] && [ "$2" = "true"  ]; then echo "ENABLED"
+  elif [ "$1" = "false" ] && [ "$2" = "false" ]; then echo "DISABLED"
+  else echo "CONFIGURED"; fi
+}
+
+emit_json() { # $1 = recording bool, $2 = transcription bool, $3 = status, $4 = preserved JSON
+  jq -n --arg apiVersion "$API_VERSION" --arg status "$3" \
+        --argjson recording "$1" --argjson transcription "$2" --argjson preserved "$4" \
     '{
       type: "ThunderbirdVoiceSettings",
       fullName: "ThunderbirdVoice",
@@ -150,8 +202,8 @@ emit_json() { # $1 = status, $2 = preserved siblings JSON array
       method: "sf project deploy (Settings/ThunderbirdVoice)",
       headless: true,
       preferences: [
-        { name: "enableCallRecording", enabled: true },
-        { name: "enableCallTranscription", enabled: true }
+        { name: "enableCallRecording", enabled: $recording },
+        { name: "enableCallTranscription", enabled: $transcription }
       ],
       preserved: $preserved,
       status: $status
@@ -159,9 +211,11 @@ emit_json() { # $1 = status, $2 = preserved siblings JSON array
 }
 
 if [ "$DRY_RUN" = "true" ]; then
-  # Siblings are still at their retrieved values in the local file (only the two
-  # targets were flipped in step 2); report them as preserved.
-  emit_json "VALIDATED" "$(extract_preserved "$SETTINGS_FILE")"
+  # The local file already reflects the requested change (targets flipped, the
+  # rest at their retrieved values); report both prefs from it.
+  REC_FINAL="$(read_pref "$SETTINGS_FILE" enableCallRecording)"
+  TRANS_FINAL="$(read_pref "$SETTINGS_FILE" enableCallTranscription)"
+  emit_json "$REC_FINAL" "$TRANS_FINAL" "VALIDATED" "$(extract_preserved "$SETTINGS_FILE")"
   exit 0
 fi
 
@@ -173,9 +227,14 @@ fi
 rm -f "$SETTINGS_FILE"
 ( cd "$PROJ" && sf project retrieve start -x package.xml -o "$TARGET_ORG" >/dev/null 2>&1 ) \
   || fail "post-deploy retrieve failed; cannot verify."
-grep -q '<enableCallRecording>true</enableCallRecording>'         "$SETTINGS_FILE" || fail "verification failed: org did not return enableCallRecording=true."
-grep -q '<enableCallTranscription>true</enableCallTranscription>' "$SETTINGS_FILE" || fail "verification failed: org did not return enableCallTranscription=true."
+
+REC_FINAL="$(read_pref "$SETTINGS_FILE" enableCallRecording)"
+TRANS_FINAL="$(read_pref "$SETTINGS_FILE" enableCallTranscription)"
+# Each targeted field must come back at the requested state (untargeted fields
+# are whatever the org holds — reported, not asserted).
+[ -z "$REC_STATE" ]   || [ "$REC_FINAL" = "$REC_STATE" ]     || fail "verification failed: org did not return enableCallRecording=${REC_STATE} (got ${REC_FINAL})."
+[ -z "$TRANS_STATE" ] || [ "$TRANS_FINAL" = "$TRANS_STATE" ] || fail "verification failed: org did not return enableCallTranscription=${TRANS_STATE} (got ${TRANS_FINAL})."
 
 # Report siblings from the post-deploy round-tripped file — their real, current
 # (unchanged) values, proving nothing else moved.
-emit_json "ENABLED" "$(extract_preserved "$SETTINGS_FILE")"
+emit_json "$REC_FINAL" "$TRANS_FINAL" "$(compute_status "$REC_FINAL" "$TRANS_FINAL")" "$(extract_preserved "$SETTINGS_FILE")"

package/skills/service-omni-agent-users-create/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: service-omni-agent-users-create
+description: "Create reusable agent users for Omni-Channel setup and routing validation. TRIGGER when users ask to create Omni agents, provision Omni test users, seed sandbox users for routing, create Omni-Channel routing agents, or repair missing demo agents. DO NOT TRIGGER for queue membership, permission-set assignment, or supervisor-user creation."
+allowed-tools: Bash Read Write Edit Glob Grep
+metadata:
+  version: "1.0"
+  domains: ["Service"]
+  minApiVersion: "66.0"
+  relatedSkills:
+    - "service-omni-base-settings-configure"
+    - "service-omni-channel-setup-coordinate"
+    - "service-omni-permission-set-assign"
+    - "service-omni-queue-members-assign"
+    - "service-omni-supervisor-users-create"
+  accessCheck:
+    - type: license
+      value: ServiceCloud
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6"
+    - tool: ["python3"]
+      semver: ">=3.9"
+    - tool: ["sf"]
+      semver: ">=2.139.6"
+---
+
+# service-omni-agent-users-create
+
+Create N agent users on a Salesforce org via Anonymous Apex so Omni-Channel has agents to route work to. Usernames follow a deterministic per-org pattern, detection is SOQL-based, and the skill inserts only the users that are missing — so it is safe to re-run. It is invoked by `service-omni-channel-setup-coordinate` after `service-omni-base-settings-configure` enables Omni-Channel; assigning permission sets (`service-omni-permission-set-assign`) and adding users to queues (`service-omni-queue-members-assign`) are separate leaves. Supervisor users come from `service-omni-supervisor-users-create`.
+
+## Inputs
+
+Confirm once, up front:
+
+- `org-alias` (required, no default) — must resolve via `sf org display`.
+- User count (optional, default `3`, range `1..10`).
+- Profile name (optional, default `Standard User` for portability). The coordinator overrides this to a Service Cloud profile so agents consume Service Cloud licenses; on many CDOs the Salesforce license pool is saturated while Service Cloud has free slots.
+
+Usernames and passwords are never accepted from the operator — both are generated (usernames from the org suffix, passwords via Anonymous Apex). Operator-supplied credentials would break re-run detection and risk weak or leaked secrets.
+
+## 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.
+- The executing user has `PermissionsModifyAllData` and `PermissionsManagePasswordPolicies` (standard on System Administrator).
+- **Production guardrail:** the detect script computes `safe_to_write` as `IsSandbox` OR `TrialExpirationDate != null` OR `OrganizationType` in {Developer Edition, Base Edition}, and the skill blocks with no override when it is false. CDOs, scratch orgs, and dev orgs are permitted.
+
+**Password handling (fail-closed).** Passwords are set by Anonymous Apex `System.setPassword` (`sf user password generate` cannot target Apex-inserted users — it fails with `NamedOrgNotFoundError`). The password literal appears in the inline executeAnonymous debug log and, only when a debug-log TraceFlag is active for the running user, in a queryable `ApexLog`. The wrapper therefore fails closed *before* the first `System.setPassword`: it proves via a SOQL-filtered Tooling API query (`ExpirationDate > now`) that no active TraceFlag exists. If safety cannot be positively proven — the running user is unresolved, the query fails or is unparseable, or any active TraceFlag exists — it generates no password at all; the user is left ACTIVE, flagged `password_status:"reset_required"`, and a `security_warning` explains why. It never deletes logs, so no plaintext can reach an `ApexLog` and unrelated audit logs are untouched. If `System.setPassword` itself fails for a user, that user is kept ACTIVE and flagged for reset.
+
+## Run
+
+```bash
+# read-only preview (never writes)
+bash scripts/detect-and-create.sh plan <org-alias> [count] [profile-name]
+# detect, enforce safe_to_write, then insert only the missing users
+bash scripts/detect-and-create.sh run  <org-alias> [count=3] [profile-name="Standard User"]
+```
+
+`detect-and-create.sh` is the canonical entry point: it re-runs detection, enforces the production guard, and only then inserts. Do not call `scripts/run-create.sh` directly — it is internal and does not enforce the guard on its own.
+
+## Behavior
+
+**Detection.** The detector derives an 8-char suffix from `Organization.Id` (`substring(10,18)`, lowercased), resolves the profile by name, and queries `User` for `agent{i}.<suffix>@example.com` to find which of the `count` slot indexes are occupied. A stable, deterministic pattern is what makes re-runs idempotent — the suffix is never a timestamp or UUID.
+
+**Insertion.** The Apex loads `assets/create-users.apex.template`, substitutes `__COUNT__`/`__PROFILE_ID__`/`__SUFFIX__`, and inserts only the missing indexes. It re-checks existing users inside the transaction, which prevents a single run from double-inserting; across *concurrent* runs the in-transaction check is not a guarantee (both can pass their pre-query before either commits), so duplicate protection there relies on the global username-uniqueness constraint plus the `DUPLICATE_USERNAME` retry (see references/apex-template-notes.md). It enables the Service Cloud feature (`UserPermissionsSupportUser=true`) so users can go online in Omni; if the profile's license does not allow it, the Apex strips the flag and retries (users are still created, but need a Service-Cloud-license profile for full Omni). Each created user is reported via `AGENT_USER_CREATED|<id>|<username>|<email>` (no password in the marker — passwords are set by the separate `System.setPassword` submission).
+
+**Verification.** After insertion the detector re-runs and must show `missing_count == 0`; otherwise the skill fails (the Apex reported success but the users did not persist).
+
+## Output contract
+
+`detect-and-create.sh` emits a single JSON object with `status` ∈ `created` | `partial` | `reused` | `action_needed` | `blocked`, plus `detect` (mirrors the detector), `create` (mirrors the inserter, `null` when nothing was created), top-level `reused_users`, `created_count`, `reused_count`, `total_present_after`, `users_needing_password_reset`, `action_required`, and `safe_to_write`. The coordinator combines `reused_users` with newly created users so mixed runs configure presence and skills for the complete requested agent set.
+
+- `created` — every missing index landed with a working password.
+- `partial` — some landed but not all, or any user needs a manual password reset, or inactive occupants were found.
+- `reused` — all requested users already existed; nothing created.
+- `action_needed` — plan mode only; reports missing indexes without writing.
+- `blocked` — precondition failed (`safe_to_write=false`, unresolved profile/suffix, or nothing inserted).
+
+`create.created_users[].password` is populated only for users created this run whose `System.setPassword` succeeded; `password_status:"reset_required"` means the user is ACTIVE but has no working password yet. Exit code is 0 for `created`/`partial`/`action_needed`/`reused`, 1 for `blocked`.
+
+Generated passwords are a secret: the returned JSON is the only place they appear. Any caller that persists stdout must write it only to a restricted `CREDENTIALS.json` (mode 0600), redact it from every other artifact, and delete it after distribution — the coordinator does this automatically; standalone callers own it. Reused users' passwords are not retrievable; recover via Setup → Users → Reset Password.
+
+## Limitations
+
+- Username pattern and org suffix are fixed and never operator-configurable — that determinism is what enables idempotent re-runs.
+- Creates only agent users on the given profile; it never deletes, deactivates, or mutates existing users.
+- Common User errors (`DUPLICATE_USERNAME`, `INVALID_EMAIL`, `LICENSE_LIMIT_EXCEEDED`) are translated into operator-friendly messages rather than surfaced raw.
+
+## References
+
+| File | When to read |
+|---|---|
+| `references/apex-patterns.md` | Before running the Apex — Apex structure, User field defaults, password policy, and the profile-localization risk |
+| `references/apex-template-notes.md` | When user creation returns a duplicate, license, or password error — explains template substitutions and retry behavior |
+| `assets/create-users.apex.template` | Loaded by `scripts/run-create.sh` when missing agent users must be inserted |
+| `scripts/detect-existing.sh` | Loaded by the canonical entry point for the read-only org, profile, safety, and existing-user checks |
+| `scripts/tests/test_user_create_security.py` | Run after changing the user-creation scripts to verify production refusal and password-handling contracts |

package/skills/service-omni-agent-users-create/assets/create-users.apex.template

@@ -0,0 +1,80 @@
+// service-omni-agent-users-create - Anonymous Apex asset template. Tokens __COUNT__/__PROFILE_ID__/__SUFFIX__ resolved by run-create.sh. Idempotency, password/TraceFlag security note, output contract: references/apex-template-notes.md.
+
+Integer requested = __COUNT__;
+String profileId  = '__PROFILE_ID__';
+String suffix     = '__SUFFIX__';
+
+Map<String, Integer> expectedByUsername = new Map<String, Integer>();
+for (Integer i = 1; i <= requested; i++) {
+    expectedByUsername.put('agent' + i + '.' + suffix + '@example.com', i);
+}
+
+Set<String> existingUsernames = new Set<String>();
+for (User u : [SELECT Username FROM User WHERE Username IN :expectedByUsername.keySet()]) {
+    existingUsernames.add(u.Username.toLowerCase());
+}
+
+List<User> toInsert = new List<User>();
+
+for (Integer i = 1; i <= requested; i++) {
+    String uname = 'agent' + i + '.' + suffix + '@example.com';
+    if (existingUsernames.contains(uname.toLowerCase())) {
+        continue;
+    }
+
+    // Alias must be <= 8 chars - 'omag' (4) + index + trailing suffix chars.
+    String aliasStr;
+    if (i < 10) {
+        aliasStr = 'omag' + i + suffix.substring(suffix.length() - 3);
+    } else {
+        aliasStr = 'omag' + i + suffix.substring(suffix.length() - 2);
+    }
+
+    User u = new User(
+        FirstName           = 'Omni',
+        LastName            = 'Agent' + i,
+        Email               = uname,
+        Username            = uname,
+        Alias               = aliasStr,
+        ProfileId           = profileId,
+        IsActive            = true,
+        // Service Cloud feature license - required for the user to actually go online in
+        // Omni-Channel and to hold Omni permissions. Only allowed on user licenses that
+        // support it (e.g. Salesforce); the try/catch below strips it and retries when the
+        // profile's user license rejects it (e.g. the limited "Service Cloud" user license).
+        UserPermissionsSupportUser = true,
+        TimeZoneSidKey      = 'America/Los_Angeles',
+        LocaleSidKey        = 'en_US',
+        EmailEncodingKey    = 'UTF-8',
+        LanguageLocaleKey   = 'en_US'
+    );
+    toInsert.add(u);
+}
+
+if (toInsert.isEmpty()) {
+    System.debug('AGENT_USERS_ALL_EXIST - no inserts required');
+    return;
+}
+
+try {
+    insert toInsert;
+    System.debug('AGENT_USERS_SERVICE_CLOUD_FEATURE|enabled');
+} catch (DmlException e) {
+    // The user license behind this profile does not allow the Service Cloud feature.
+    // Fall back to creating the users without it so the skill still provisions them; the
+    // operator must move them to a Salesforce license + Service Cloud feature for full Omni.
+    if (e.getMessage() != null && e.getMessage().contains('Service Cloud User')) {
+        for (User u : toInsert) { u.UserPermissionsSupportUser = false; }
+        insert toInsert;
+        System.debug('AGENT_USERS_SERVICE_CLOUD_FEATURE|skipped_license_not_allowed');
+    } else {
+        throw e;
+    }
+}
+
+// Emit machine-parseable lines. No password field - passwords are set by a separate
+// `System.setPassword` Apex submission on the CLI side (run-create.sh), whose source
+// Salesforce does not persist to any queryable ApexLog.
+for (User u : toInsert) {
+    System.debug('AGENT_USER_CREATED|' + u.Id + '|' + u.Username + '|' + u.Email);
+}