@salesforce/afv-skills 1.57.0 → 1.58.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/afv-skills",
-  "version": "1.57.0",
+  "version": "1.58.0",
   "description": "Salesforce skills for Agentforce Vibes",
   "license": "CC-BY-NC-4.0",
   "files": [

package/skills/experience-ui-bundle-project-generate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: experience-ui-bundle-project-generate
-description: "Generates a minimal, ready-to-develop SFDX starter project from template instead of hand-scaffolding files. Use this skill when starting a brand-new Salesforce UI bundle app (React or Angular) and the initial project must be scaffolded — trigger phrases include create, start, or scaffold a new UI bundle app, generate a starter project, or use a prebuilt/starter template. DO NOT TRIGGER when: editing, styling, or adding pages or components to an EXISTING app (use experience-ui-bundle-frontend-generate); configuring ui-bundle.json or metadata files (use experience-ui-bundle-metadata-generate); deploying to an org (use experience-ui-bundle-deploy); or when the user explicitly says they want to hand-scaffold from scratch."
+description: "Generates a minimal, ready-to-develop SFDX starter project from template instead of hand-scaffolding files. Use this skill when starting a brand-new Salesforce UI bundle app (React or Angular) and the initial project must be scaffolded — trigger phrases include create, start, or scaffold a new UI bundle app, generate a starter project, or use a prebuilt/starter template. DO NOT TRIGGER when: editing, styling, or adding pages or components to an EXISTING app (use experience-ui-bundle-frontend-generate); configuring ui-bundle.json or metadata files (use experience-ui-bundle-metadata-generate); deploying to an org (use experience-ui-bundle-deploy); when the user explicitly says they want to hand-scaffold from scratch; or when creating a brand-new standalone Salesforce project that also needs full setup — relocating the session, connecting an org, setting the default, and enabling source tracking (use dx-project-create in the salesforce-development plugin)."
 metadata:
   version: "1.2"
   domains: ["Experience"]
@@ -42,39 +42,22 @@ Once the user picks, carry the chosen `--template` flag into Step 2.
 
 ## Step 2: Generate the project into the target root
 
-The project contents must land **directly at the target root `$DEST`** — so `sfdx-project.json` sits at `$DEST/sfdx-project.json`, with no extra wrapper subfolder. `sf template generate project` always nests its output under a `--name` subfolder, so generate into the `$DEST` dir, then move the contents from the subfolder up into `$DEST`, overwriting anything already there on conflict. Remove the empty subfolder at the end.
+The project contents must land **directly at the target root `$DEST`** — so `sfdx-project.json` sits at `$DEST/sfdx-project.json`, with no extra wrapper subfolder. `sf template generate project` always nests its output under a `--name` subfolder, so `<SKILL_DIR>/scripts/generate-project.mjs` generates into `$DEST`, flattens the subfolder's contents up into `$DEST` (overwriting anything already there on conflict), and removes the now-empty subfolder — all through Node's `fs`/`child_process` APIs, so it runs the same way on Windows cmd/PowerShell as it does on macOS/Linux/Git Bash.
 
 - `<SKILL_DIR>` = the absolute path to **this skill's own directory** — the folder containing this `SKILL.md`; resolve it from the skill path in context
 - **`$NAME`** — the project name (alphanumerical only — no spaces, hyphens, underscores, or special characters). Ask the user for it. It also names the UI bundle, so it shows up inside the project.
 - **`$DEST`** — the target root directory the contents land in (use `.` for the current directory).
+- **`$TEMPLATE`** — the `--template` flag value from the framework reference chosen in Step 1 (e.g. `reactinternalapp`).
 
-```sh
-NAME=MyApp   # project name the user chose; also names the UI bundle
-DEST=.       # target root directory (the contents land directly here, no NAME/ wrapper)
-
-# the --template flag from the framework reference chosen in Step 1
-TEMPLATE=reactinternalapp   # example placeholder — replace with the flag from your Step-1 reference
-
-mkdir -p "$DEST"
-sf template generate project --name "$NAME" --template "$TEMPLATE" --output-dir "$DEST"
-
-# Flatten the generated $DEST/$NAME contents up into $DEST (see <SKILL_DIR>/scripts/flatten-project.mjs).
-# Use the absolute skill-dir path — a relative ./scripts/ would resolve against $DEST, not the skill.
-node "<SKILL_DIR>/scripts/flatten-project.mjs" "$DEST/$NAME" "$DEST"
-rm -rf "$DEST/$NAME"
-```
-
-> `<SKILL_DIR>/scripts/flatten-project.mjs` moves every generated entry (incl. dotfiles) into `$DEST`, overwriting any existing file/dir of any type on conflict while preserving unrelated files the user already had in `$DEST`. The per-entry `rmSync` + `renameSync` is what guarantees the template's files win on conflict (including a file-vs-directory type mismatch).
-
-### Verify
-
-After generation, confirm the contents landed at the root (not in a `$NAME/` subfolder):
+Run the script with the actual, literal values substituted for `$NAME`, `$DEST`, and `$TEMPLATE` — do not use shell variable assignment/interpolation (`NAME=...` / `$NAME` / `%NAME%` / `$env:NAME`) since that syntax differs across bash, cmd, and PowerShell and this command must work in all three:
 
 ```sh
-test -f "$DEST/sfdx-project.json" && echo "OK: project root landed" || echo "FAILED"
+node "<SKILL_DIR>/scripts/generate-project.mjs" "<name>" "<dest>" "<template>"
 ```
 
-`sfdx-project.json` must sit at `$DEST/sfdx-project.json`. The project also contains `package.json`, `force-app/main/default/uiBundles/$NAME/` (the UI bundle), `scripts/`, `config/`, and `README.md`. See the framework reference from Step 1 for the specific bundle contents. If `sfdx-project.json` is missing or is one level down in `$DEST/$NAME/`, the flatten did not run — re-check before continuing.
+The script prints `OK: project root landed at <dest> (...)` and exits 0 on success. It exits non-zero (with a clear stderr message) if `sf template generate project` fails, the generated project has no `sfdx-project.json`, or the flatten didn't leave a valid project root — stop and surface the failure rather than continuing.
+
+`sfdx-project.json` must sit at `$DEST/sfdx-project.json`. The project also contains `package.json`, `force-app/main/default/uiBundles/$NAME/` (the UI bundle), `scripts/`, `config/`, and `README.md`. See the framework reference from Step 1 for the specific bundle contents.
 
 ## Step 3: Install dependencies (you do this — do NOT hand off uninstalled)
 
@@ -84,26 +67,17 @@ There are **multiple** `package.json` files, each needing its own install:
 - the **project root** (`$DEST/package.json`), and
 - the **UI bundle** dir under `$DEST/force-app/main/default/uiBundles/$NAME/` — this holds the toolchain the preview server loads, so it must have `node_modules` too.
 
-```sh
-# 1. project root ($DEST was set in Step 2)
-( cd "$DEST" && npm install )
+`<SKILL_DIR>/scripts/install-deps.mjs` runs `npm install` for the root and for every UI bundle that has a `package.json` (via Node's `child_process` with an explicit `cwd` — no `cd &&` shell chaining), then verifies `node_modules` landed everywhere it installed:
 
-# 2. each UI bundle
-for b in "$DEST"/force-app/main/default/uiBundles/*/; do
-  [ -f "$b/package.json" ] && ( cd "$b" && npm install )
-done
+```sh
+node "<SKILL_DIR>/scripts/install-deps.mjs" "<dest>"
 ```
 
-> First-run install of the bundle is the heavy step; expect a short wait. If an install fails, surface it — don't hand off a half-installed project.
+Substitute the literal `$DEST` value from Step 2 for `<dest>`. The script prints `OK: all dependencies installed.` and exits 0 on success; it exits non-zero with a listed summary of which install(s) failed otherwise. First-run install of the bundle is the heavy step; expect a short wait. If an install fails, surface it — don't hand off a half-installed project.
 
 ## Step 4: Confirm and hand off
 
-Verify the project landed and is installed:
-
-```sh
-ls "$DEST" # sfdx-project.json, package.json, force-app/, scripts/, README.md ...
-ls "$DEST"/force-app/main/default/uiBundles/*/node_modules >/dev/null && echo "bundle deps installed"
-```
+`install-deps.mjs` already prints a verification summary (root + each UI bundle's `node_modules`) as part of Step 3. To look around the generated project yourself, use your own file-listing/read tools rather than a shell `ls` — that works identically regardless of the underlying OS shell.
 
 The project is now ready to develop and deploy. If there's a `README.md` in the template, take a look at it to see if there is any extra step or guidance for the user.
 

package/skills/experience-ui-bundle-project-generate/scripts/flatten-project.mjs

@@ -10,24 +10,46 @@
 // — only the paths the template ships get replaced. The per-entry rmSync + renameSync is what
 // guarantees the template's files win on conflict (including a file-vs-directory type mismatch).
 // Requires Node ≥ 16.7 for rmSync.
+//
+// Always invoke via `node` (never as a bare executable) so this works on Windows cmd/PowerShell
+// as well as macOS/Linux/Git Bash. Uses fs/path APIs only — no shell-out — so path separators and
+// move semantics are correct on every OS.
 
 import fs from "node:fs";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 
-const [src, dest] = process.argv.slice(2);
+export function flattenProject(src, dest) {
+  if (!fs.existsSync(path.join(src, "sfdx-project.json"))) {
+    throw new Error("generated project has no sfdx-project.json: " + src);
+  }
 
-if (!src || !dest) {
-  console.error("usage: node <skill_dir>/scripts/flatten-project.mjs <srcDir> <destDir>");
-  process.exit(1);
+  for (const entry of fs.readdirSync(src)) {
+    const target = path.join(dest, entry);
+    fs.rmSync(target, { recursive: true, force: true });
+    fs.renameSync(path.join(src, entry), target);
+  }
 }
 
-if (!fs.existsSync(path.join(src, "sfdx-project.json"))) {
-  console.error("generated project has no sfdx-project.json: " + src);
-  process.exit(1);
+function main() {
+  const [src, dest] = process.argv.slice(2);
+
+  if (!src || !dest) {
+    console.error("usage: node <skill_dir>/scripts/flatten-project.mjs <srcDir> <destDir>");
+    process.exit(1);
+  }
+
+  try {
+    flattenProject(src, dest);
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
 }
 
-for (const entry of fs.readdirSync(src)) {
-  const target = path.join(dest, entry);
-  fs.rmSync(target, { recursive: true, force: true });
-  fs.renameSync(path.join(src, entry), target);
+// Only run as a CLI when invoked directly (not when imported by generate-project.mjs).
+// pathToFileURL handles Windows drive letters/backslashes correctly (a manual
+// `file://${path}` string would not).
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main();
 }

package/skills/experience-ui-bundle-project-generate/scripts/generate-project.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// Generate a `sf template generate project` starter and flatten it so the
+// contents land directly at the target root (no `<name>/` wrapper subfolder).
+//
+// Usage: node <skill_dir>/scripts/generate-project.mjs <name> <dest> <template>
+//   <name>     — project name passed to `sf template generate project --name`
+//   <dest>     — target root directory the contents should land in
+//                (so sfdx-project.json sits at <dest>/sfdx-project.json)
+//   <template> — the `--template` flag value from the chosen framework reference
+//
+// Always invoke via `node` (never as a bare executable, and never wrap this
+// in a bash/cmd/PowerShell script) so this works on Windows cmd/PowerShell
+// as well as macOS/Linux/Git Bash. Pass <name>/<dest>/<template> as literal
+// argv values — do not rely on shell variable assignment/interpolation
+// (`$VAR` / `%VAR%` / `$env:VAR` differ per shell).
+//
+// Runs `sf` via spawnSync with shell:true so the platform's own shell
+// resolves the CLI shim correctly (on Windows, globally-installed CLIs are
+// usually `.cmd`/`.ps1` wrappers that spawn() cannot find without a shell).
+//
+// Exit 0 on success (project landed at <dest>).
+// Exit 1 if `sf template generate project` fails, the generated project has
+// no sfdx-project.json, or the flatten didn't result in a valid project root.
+
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { flattenProject } from "./flatten-project.mjs";
+
+const [name, dest, template] = process.argv.slice(2);
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+if (!name || !dest || !template) {
+  fail("usage: node <skill_dir>/scripts/generate-project.mjs <name> <dest> <template>");
+}
+
+fs.mkdirSync(dest, { recursive: true });
+
+const result = spawnSync(
+  "sf",
+  ["template", "generate", "project", "--name", name, "--template", template, "--output-dir", dest],
+  { stdio: "inherit", shell: true },
+);
+
+if (result.error) {
+  fail(`ERROR: failed to run "sf template generate project": ${result.error.message}`);
+}
+if (result.status !== 0) {
+  process.exit(result.status ?? 1);
+}
+
+const srcDir = path.join(dest, name);
+
+if (!fs.existsSync(path.join(srcDir, "sfdx-project.json"))) {
+  fail(`ERROR: generated project has no sfdx-project.json: ${srcDir}`);
+}
+
+try {
+  flattenProject(srcDir, dest);
+} catch (err) {
+  fail(`ERROR: ${err.message}`);
+}
+
+// Remove the now-empty (or leftover) generated subfolder.
+fs.rmSync(srcDir, { recursive: true, force: true });
+
+const destProjectFile = path.join(dest, "sfdx-project.json");
+if (!fs.existsSync(destProjectFile)) {
+  fail(`FAILED: sfdx-project.json not found at ${destProjectFile} — flatten did not run correctly`);
+}
+
+console.log(`OK: project root landed at ${dest} (${destProjectFile})`);
+process.exit(0);

package/skills/experience-ui-bundle-project-generate/scripts/install-deps.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// Install dependencies for a generated UI bundle starter project: the
+// project root `package.json`, plus each `package.json` under
+// force-app/main/default/uiBundles/*/ (the toolchain the preview server
+// loads). Then verify node_modules landed everywhere it was installed.
+//
+// Usage: node <skill_dir>/scripts/install-deps.mjs <dest>
+//   <dest> — the project root (same value passed to generate-project.mjs)
+//
+// Always invoke via `node` (never as a bare executable, and never wrap this
+// in a bash/cmd/PowerShell script) so this works on Windows cmd/PowerShell
+// as well as macOS/Linux/Git Bash. Runs `npm install` via spawnSync with an
+// explicit `cwd` (no `cd &&` subshell chaining) and shell:true so the
+// platform's own shell resolves the `npm` CLI shim correctly.
+//
+// Exit 0 if every install succeeded (or there was nothing to install).
+// Exit 1 with a summary of which installs failed — surface it, don't hand
+// off a half-installed project.
+
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const [dest] = process.argv.slice(2);
+
+if (!dest) {
+  console.error("usage: node <skill_dir>/scripts/install-deps.mjs <dest>");
+  process.exit(1);
+}
+
+function npmInstall(cwd) {
+  console.log(`Running "npm install" in ${cwd} ...`);
+  const result = spawnSync("npm", ["install"], { cwd, stdio: "inherit", shell: true });
+  if (result.error) {
+    return `${cwd}: ${result.error.message}`;
+  }
+  if (result.status !== 0) {
+    return `${cwd}: npm install exited with code ${result.status}`;
+  }
+  return null;
+}
+
+const failures = [];
+
+// 1. Project root.
+if (fs.existsSync(path.join(dest, "package.json"))) {
+  const failure = npmInstall(dest);
+  if (failure) failures.push(failure);
+} else {
+  console.error(`ERROR: no package.json found at project root: ${dest}`);
+  failures.push(`${dest}: missing package.json`);
+}
+
+// 2. Each UI bundle.
+const bundlesDir = path.join(dest, "force-app", "main", "default", "uiBundles");
+const bundleDirs = fs.existsSync(bundlesDir)
+  ? fs
+      .readdirSync(bundlesDir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => path.join(bundlesDir, entry.name))
+  : [];
+
+for (const bundleDir of bundleDirs) {
+  if (fs.existsSync(path.join(bundleDir, "package.json"))) {
+    const failure = npmInstall(bundleDir);
+    if (failure) failures.push(failure);
+  }
+}
+
+// 3. Verify node_modules landed everywhere it was installed.
+console.log("\nVerifying installs:");
+let allInstalled = true;
+if (fs.existsSync(path.join(dest, "package.json"))) {
+  const ok = fs.existsSync(path.join(dest, "node_modules"));
+  console.log(`  ${ok ? "OK" : "MISSING"}: ${path.join(dest, "node_modules")}`);
+  allInstalled = allInstalled && ok;
+}
+for (const bundleDir of bundleDirs) {
+  if (fs.existsSync(path.join(bundleDir, "package.json"))) {
+    const ok = fs.existsSync(path.join(bundleDir, "node_modules"));
+    console.log(`  ${ok ? "OK" : "MISSING"}: ${path.join(bundleDir, "node_modules")}`);
+    allInstalled = allInstalled && ok;
+  }
+}
+
+if (failures.length > 0 || !allInstalled) {
+  console.error("\nFAILED: one or more installs did not complete:");
+  for (const failure of failures) {
+    console.error(`  - ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log("\nOK: all dependencies installed.");
+process.exit(0);

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

@@ -13,6 +13,7 @@ metadata:
     - "service-omni-base-settings-configure"
     - "service-omni-channel-inventory-analyze"
     - "service-omni-command-center-analyze"
+    - "service-omni-command-center-configure"
     - "service-omni-permission-set-assign"
     - "service-omni-presence-status-deploy"
     - "service-omni-presence-user-config-deploy"

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

@@ -8,6 +8,7 @@ metadata:
   minApiVersion: "66.0"
   relatedSkills:
     - "service-omni-channel-setup-coordinate"
+    - "service-omni-command-center-configure"
     - "service-omni-supervisor-config-deploy"
   accessCheck:
     - type: license

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

@@ -0,0 +1,92 @@
+---
+name: service-omni-command-center-configure
+description: "Use to enable Command Center for Service V2 and configure its supported supervisor controls through the OmniChannel Settings Metadata API while preserving unrelated settings. Requires explicit apply consent, refuses production customer orgs, and verifies the seeded V2 page and tab. TRIGGER when: enable Command Center V2, configure conversation monitoring, enable agent sneak peek, enable customer sneak peek, configure whisper messaging, or enable queues and skills actions. Do not use to assign supervisor permissions or configure classic OmniSupervisorConfig metadata."
+allowed-tools: Bash Read Write Edit Grep Glob
+metadata:
+  version: "1.0"
+  domains: ["Service"]
+  minApiVersion: "69.0"
+  relatedSkills:
+    - "service-omni-base-settings-configure"
+    - "service-omni-channel-setup-coordinate"
+    - "service-omni-command-center-analyze"
+    - "service-omni-supervisor-config-deploy"
+  accessCheck:
+    - type: license
+      value: ServiceCloud
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6"
+    - tool: ["python3"]
+      semver: ">=3.8"
+    - tool: ["sf"]
+      semver: ">=2.139.6"
+---
+
+# service-omni-command-center-configure
+
+Enable Command Center for Service V2 through `Settings:OmniChannel` and optionally configure the five supervisor controls exposed by the same Metadata API contract. The writer retrieves the org's complete settings document, changes only requested elements, deploys that preserved document, retrieves it again, and verifies both the values and the platform-created `CommandCenterForServiceV2_L` page and V2 tab.
+
+The skill fails closed with `platform_api_unavailable` when the retrieved settings document does not expose `enableCommandCenterForServiceV2`.
+
+Run `service-omni-base-settings-configure` first so the Omni foundation is enabled. If the org does not support Command Center V2, use `service-omni-supervisor-config-deploy` for the classic supervisor configuration instead.
+
+For an end-to-end setup, `service-omni-channel-setup-coordinate` invokes this skill only when `OMNI_COMMAND_CENTER_V2=1`; the coordinator's default supervisor path remains unchanged.
+
+## Inputs
+
+```bash
+bash scripts/configure-and-report.sh plan <org-alias> [options]
+bash scripts/configure-and-report.sh run  <org-alias> --apply [options]
+```
+
+Options:
+
+| Option | Metadata element | Values |
+|---|---|---|
+| `--conversation-monitoring` | `enableConversationMonitoring` | `true` or `false` |
+| `--agent-sneak-peek` | `enableAgentSneakPeek` | `true` or `false` |
+| `--customer-sneak-peek` | `enableClientSneakPeek` | `true` or `false` |
+| `--whisper-messaging` | `enableWhisperMessaging` | `true` or `false` |
+| `--queues-and-skills` | `enableSkillsAndQueueActions` | `true` or `false` |
+
+`enableCommandCenterForServiceV2=true` is always requested. Unspecified supervisor controls are preserved exactly as retrieved. The skill intentionally does not disable V2 because disabling an org-level supervisor experience is a materially different operation.
+
+## Safety
+
+- `plan` is read-only and never deploys.
+- `run` requires the literal `--apply` flag before any mutation.
+- Writes are allowed only when `IsSandbox=true`, `TrialExpirationDate` is non-null, or `OrganizationType` is `Developer Edition` or `Base Edition`. There is no production override.
+- `Settings` is a whole-document Metadata API type. Never deploy a partial or hardcoded `OmniChannel.settings-meta.xml`; doing so can reset unrelated Omni settings.
+- The target org must have Enhanced Omni-Channel and the Command Center for Service V2 release gater. The API field is also permission-gated by `Customize Application`.
+
+## Behavior
+
+1. Authenticate and retrieve `Settings:OmniChannel` at API v66.
+2. Confirm the V2 field is present. If it is absent, return `blocked` with `reason_code=platform_api_unavailable`; do not attempt a deploy.
+3. Build a requested-value set containing V2=`true` plus only the optional controls explicitly supplied by the caller.
+4. In `plan`, return `action_needed` or `reused` without writing.
+5. In `run`, enforce `--apply` and the non-production guard, mutate a private copy of the retrieved document, and deploy it.
+6. Retrieve the settings again and require every requested value to match.
+7. Require both the seeded `FlexiPage` (`CommandCenterForServiceV2_L`) and V2 `TabDefinition` to be observable. Missing or unreadable provisioning evidence returns `blocked`; the skill never guesses.
+
+The platform's ON-transition hook is idempotent: it creates missing profile tab configuration and seeds the baseline FlexiPage only when needed. Existing page customizations are not overwritten. If the preference is already true but its seed artifacts are missing, the skill returns `seed_incomplete`; it does not force a destructive OFF→ON cycle.
+
+## Output contract
+
+The script emits one JSON object with:
+
+- `status`: `configured`, `reused`, `action_needed`, or `blocked`
+- `reason_code`: a stable reason such as `changes_required`, `already_configured`, `platform_api_unavailable`, `unsafe_target`, `deploy_failed`, `verification_failed`, or `seed_incomplete`
+- `requested`, `before`, and `after`: setting values, with presence retained in the snapshots
+- `safe_to_write`, `deploy_id`, and `verification`
+- `manual_actions`: permission assignment and any required follow-up
+- `blocking_issue`: populated only when blocked
+
+Enabling the org preference does not grant user access. Assign a permission set containing `CommandCenterForServiceUser` to each intended supervisor, then run `service-omni-command-center-analyze <org> <supervisor>` to verify end-to-end readiness.
+
+## References
+
+| File | When to read |
+|---|---|
+| `references/api-notes.md` | Metadata names, platform gates, seed behavior, and known limitations |

package/skills/service-omni-command-center-configure/references/api-notes.md

@@ -0,0 +1,50 @@
+# Command Center for Service V2 API notes
+
+## Metadata contract
+
+Core work item `W-24039822` and Core PR `#16874` expose these fields on `Settings:OmniChannel`:
+
+| Metadata field | Product control |
+|---|---|
+| `enableCommandCenterForServiceV2` | Command Center for Service V2 |
+| `enableConversationMonitoring` | Conversation monitoring |
+| `enableAgentSneakPeek` | Agent sneak peek |
+| `enableClientSneakPeek` | Customer sneak peek |
+| `enableWhisperMessaging` | Whisper messaging |
+| `enableSkillsAndQueueActions` | Queues and skills actions |
+
+The V2 preference is Metadata API writable only when the target release contains that contract and the `OmniChannel.commandCenterForServiceV2Available` access check passes. That access check requires the feature gater and Enhanced Omni-Channel. Standard Omni orgs on the EOL extension cannot enable V2.
+
+## ON-transition side effects
+
+Changing `enableCommandCenterForServiceV2` from false to true invokes the existing `CommandCenterForServiceV2OrgPreference` hook. The hook:
+
+1. inserts missing profile tab configurations for the V2 tab;
+2. checks for `FlexiPage.DeveloperName='CommandCenterForServiceV2_L'`;
+3. clones the platform seed only when that page is absent.
+
+Disabling the preference does not delete the page. Re-enabling preserves an existing page. This skill enables but does not disable V2.
+
+## Verification signals
+
+The writer verifies the settings by a fresh Metadata API retrieve and verifies provisioning through:
+
+```sql
+SELECT Id FROM FlexiPage WHERE DeveloperName='CommandCenterForServiceV2_L'
+```
+
+using Tooling API, and:
+
+```sql
+SELECT Name FROM TabDefinition WHERE Name='standard-commandcenterforservicev2'
+```
+
+using the data API. Query errors remain `unknown` and block a successful write claim.
+
+## User access
+
+The org preference and its seed artifacts establish org-level readiness only. A supervisor also needs a permission set with `PermissionsCommandCenterForServiceUser=true`. This skill reports that follow-up but does not create users or permission sets.
+
+## Whole-document requirement
+
+Salesforce Settings metadata is deployed as a complete document. The implementation retrieves the current document and updates it in place. Do not replace this approach with a static template: a static template can silently drop existing Omni settings that are outside this skill's scope.

package/skills/service-omni-command-center-configure/scripts/configure-and-report.sh

@@ -0,0 +1,257 @@
+#!/usr/bin/env bash
+# Configure Command Center for Service V2 through a preserved OmniChannel Settings document.
+
+set -euo pipefail
+
+usage() {
+  echo '{"status":"blocked","reason_code":"invalid_arguments","blocking_issue":"Usage: bash configure-and-report.sh <plan|run> <org-alias> [--apply] [--conversation-monitoring true|false] [--agent-sneak-peek true|false] [--customer-sneak-peek true|false] [--whisper-messaging true|false] [--queues-and-skills true|false]"}' >&2
+  exit 1
+}
+
+[ "$#" -ge 2 ] || usage
+
+MODE="$1"
+ORG="$2"
+shift 2
+
+case "$MODE" in
+  plan|run) ;;
+  *) usage ;;
+esac
+
+APPLY=false
+REQUESTED_JSON='{"enableCommandCenterForServiceV2":true}'
+ASSIGNMENTS=("enableCommandCenterForServiceV2=true")
+
+add_setting() {
+  local metadata_name="$1"
+  local value="$2"
+  if [ "$value" != "true" ] && [ "$value" != "false" ]; then
+    jq -n --arg name "$metadata_name" --arg value "$value" \
+      '{status:"blocked",reason_code:"invalid_arguments",blocking_issue:("Expected true or false for " + $name + ", received: " + $value)}' >&2
+    exit 1
+  fi
+  REQUESTED_JSON=$(jq -c --arg name "$metadata_name" --argjson value "$value" '. + {($name):$value}' <<<"$REQUESTED_JSON")
+  ASSIGNMENTS+=("$metadata_name=$value")
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --apply)
+      APPLY=true
+      shift
+      ;;
+    --conversation-monitoring|--agent-sneak-peek|--customer-sneak-peek|--whisper-messaging|--queues-and-skills)
+      [ "$#" -ge 2 ] || usage
+      case "$1" in
+        --conversation-monitoring) FIELD="enableConversationMonitoring" ;;
+        --agent-sneak-peek) FIELD="enableAgentSneakPeek" ;;
+        --customer-sneak-peek) FIELD="enableClientSneakPeek" ;;
+        --whisper-messaging) FIELD="enableWhisperMessaging" ;;
+        --queues-and-skills) FIELD="enableSkillsAndQueueActions" ;;
+      esac
+      add_setting "$FIELD" "$2"
+      shift 2
+      ;;
+    *) usage ;;
+  esac
+done
+
+if [ "$MODE" = "plan" ] && [ "$APPLY" = "true" ]; then
+  jq -n '{status:"blocked",reason_code:"invalid_arguments",blocking_issue:"--apply is not valid in plan mode."}' >&2
+  exit 1
+fi
+
+if [ "$MODE" = "run" ] && [ "$APPLY" != "true" ]; then
+  jq -n --argjson requested "$REQUESTED_JSON" \
+    '{status:"blocked",reason_code:"apply_required",requested:$requested,safe_to_write:null,deploy_id:null,blocking_issue:"run mode requires explicit --apply consent; no org changes were made."}'
+  exit 1
+fi
+
+for dependency in sf jq python3; do
+  if ! command -v "$dependency" >/dev/null 2>&1; then
+    jq -n --arg dependency "$dependency" \
+      '{status:"blocked",reason_code:"missing_dependency",blocking_issue:("Required command is unavailable: " + $dependency)}' >&2
+    exit 1
+  fi
+done
+
+if ! sf org display --target-org "$ORG" --json >/dev/null 2>&1; then
+  jq -n --arg org "$ORG" \
+    '{status:"blocked",reason_code:"org_not_authenticated",blocking_issue:("Org alias is not authenticated: " + $org)}' >&2
+  exit 1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+DOCUMENT_TOOL="$SCRIPT_DIR/settings_document.py"
+WORK_DIR="$(mktemp -d "${TMPDIR:-/tmp}/omni-command-center-configure.XXXXXX")"
+trap 'rm -rf "$WORK_DIR"' EXIT
+
+create_project() {
+  local directory="$1"
+  mkdir -p "$directory/force-app/main/default"
+  printf '%s\n' '{"packageDirectories":[{"path":"force-app","default":true}],"sourceApiVersion":"66.0"}' > "$directory/sfdx-project.json"
+}
+
+retrieve_settings() {
+  local directory="$1"
+  create_project "$directory"
+  (cd "$directory" && sf project retrieve start --target-org "$ORG" --metadata "Settings:OmniChannel" --json >/dev/null 2>&1)
+}
+
+settings_path() {
+  printf '%s/force-app/main/default/settings/OmniChannel.settings-meta.xml' "$1"
+}
+
+if ! retrieve_settings "$WORK_DIR/before"; then
+  jq -n --argjson requested "$REQUESTED_JSON" \
+    '{status:"blocked",reason_code:"retrieve_failed",requested:$requested,blocking_issue:"Could not retrieve Settings:OmniChannel. Verify org access and retry."}'
+  exit 1
+fi
+
+BEFORE_XML="$(settings_path "$WORK_DIR/before")"
+if [ ! -f "$BEFORE_XML" ]; then
+  jq -n --argjson requested "$REQUESTED_JSON" \
+    '{status:"blocked",reason_code:"retrieve_failed",requested:$requested,blocking_issue:"The retrieve completed without an OmniChannel settings document."}'
+  exit 1
+fi
+
+if ! BEFORE_JSON=$(python3 "$DOCUMENT_TOOL" inspect "$BEFORE_XML" 2>/dev/null); then
+  jq -n --argjson requested "$REQUESTED_JSON" \
+    '{status:"blocked",reason_code:"invalid_settings_document",requested:$requested,blocking_issue:"The retrieved OmniChannel settings document could not be parsed."}'
+  exit 1
+fi
+
+API_PRESENT=$(jq -r '.settings.enableCommandCenterForServiceV2.present' <<<"$BEFORE_JSON")
+if [ "$API_PRESENT" != "true" ]; then
+  jq -n --argjson requested "$REQUESTED_JSON" --argjson before "$BEFORE_JSON" \
+    '{status:"blocked",reason_code:"platform_api_unavailable",requested:$requested,before:$before,after:null,safe_to_write:null,deploy_id:null,verification:null,manual_actions:[{id:"WAIT_FOR_W_24039822",title:"Use a target release containing the W-24039822 Metadata API contract (Core PR #16874)."}],blocking_issue:"The target org does not expose enableCommandCenterForServiceV2 in Settings:OmniChannel; no deployment was attempted."}'
+  exit 1
+fi
+
+values_match() {
+  local snapshot="$1"
+  jq -ne --argjson requested "$REQUESTED_JSON" --argjson snapshot "$snapshot" '
+    all($requested | to_entries[];
+      (.key as $name | .value as $wanted |
+        $snapshot.settings[$name].present == true and $snapshot.settings[$name].value == $wanted)
+    )
+  ' >/dev/null
+}
+
+query_verification() {
+  local seed_json tab_json seed tab
+  seed_json=$(sf data query --target-org "$ORG" --use-tooling-api --json \
+    --query "SELECT Id FROM FlexiPage WHERE DeveloperName='CommandCenterForServiceV2_L'" 2>/dev/null || true)
+  if [ "$(jq -r '.status // 1' <<<"$seed_json" 2>/dev/null)" = "0" ]; then
+    if [ "$(jq -r '.result.totalSize // 0' <<<"$seed_json")" -gt 0 ]; then seed=true; else seed=false; fi
+  else
+    seed=unknown
+  fi
+
+  tab_json=$(sf data query --target-org "$ORG" --json \
+    --query "SELECT Name FROM TabDefinition WHERE Name='standard-commandcenterforservicev2' LIMIT 1" 2>/dev/null || true)
+  if [ "$(jq -r '.status // 1' <<<"$tab_json" 2>/dev/null)" = "0" ]; then
+    if [ "$(jq -r '.result.totalSize // 0' <<<"$tab_json")" -gt 0 ]; then tab=true; else tab=false; fi
+  else
+    tab=unknown
+  fi
+
+  jq -n --arg seed "$seed" --arg tab "$tab" \
+    '{seed_flexipage_present:$seed,v2_tab_present:$tab,complete:($seed == "true" and $tab == "true")}'
+}
+
+BEFORE_MATCH=false
+if values_match "$BEFORE_JSON"; then BEFORE_MATCH=true; fi
+
+if [ "$BEFORE_MATCH" = "true" ]; then
+  VERIFY_JSON=$(query_verification)
+  if [ "$(jq -r '.complete' <<<"$VERIFY_JSON")" != "true" ]; then
+    jq -n --argjson requested "$REQUESTED_JSON" --argjson before "$BEFORE_JSON" --argjson verification "$VERIFY_JSON" \
+      '{status:"blocked",reason_code:"seed_incomplete",requested:$requested,before:$before,after:$before,safe_to_write:null,deploy_id:null,verification:$verification,manual_actions:[{id:"REPAIR_V2_SEED",title:"The V2 preference is already enabled but its page or tab cannot be proven. Diagnose the platform seed before retrying; this skill will not force an OFF-to-ON cycle."}],blocking_issue:"Command Center V2 is enabled but its seed artifacts are missing or unreadable."}'
+    exit 1
+  fi
+
+  jq -n --argjson requested "$REQUESTED_JSON" --argjson before "$BEFORE_JSON" --argjson verification "$VERIFY_JSON" \
+    '{status:"reused",reason_code:"already_configured",requested:$requested,before:$before,after:$before,safe_to_write:null,deploy_id:null,verification:$verification,manual_actions:[{id:"ASSIGN_V2_PERMISSION",title:"Assign CommandCenterForServiceUser to each intended supervisor, then verify with service-omni-command-center-analyze."}],blocking_issue:null}'
+  exit 0
+fi
+
+if [ "$MODE" = "plan" ]; then
+  jq -n --argjson requested "$REQUESTED_JSON" --argjson before "$BEFORE_JSON" \
+    '{status:"action_needed",reason_code:"changes_required",requested:$requested,before:$before,after:null,safe_to_write:null,deploy_id:null,verification:null,manual_actions:[],blocking_issue:null}'
+  exit 0
+fi
+
+ORG_GUARD_JSON=$(sf data query --target-org "$ORG" --json \
+  --query "SELECT IsSandbox, TrialExpirationDate, OrganizationType FROM Organization LIMIT 1" 2>/dev/null || true)
+if [ "$(jq -r '.status // 1' <<<"$ORG_GUARD_JSON" 2>/dev/null)" != "0" ]; then
+  jq -n --argjson requested "$REQUESTED_JSON" --argjson before "$BEFORE_JSON" \
+    '{status:"blocked",reason_code:"guard_query_failed",requested:$requested,before:$before,safe_to_write:null,deploy_id:null,blocking_issue:"Could not evaluate the non-production safe_to_write guard."}'
+  exit 1
+fi
+
+IS_SANDBOX=$(jq -r '.result.records[0].IsSandbox' <<<"$ORG_GUARD_JSON")
+TRIAL_EXP=$(jq -r '.result.records[0].TrialExpirationDate // "null"' <<<"$ORG_GUARD_JSON")
+ORG_TYPE=$(jq -r '.result.records[0].OrganizationType // ""' <<<"$ORG_GUARD_JSON")
+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 requested "$REQUESTED_JSON" --argjson before "$BEFORE_JSON" \
+    '{status:"blocked",reason_code:"unsafe_target",requested:$requested,before:$before,safe_to_write:false,deploy_id:null,blocking_issue:"Refusing to configure Command Center V2 in a production customer org."}'
+  exit 1
+fi
+
+create_project "$WORK_DIR/deploy"
+DEPLOY_XML="$(settings_path "$WORK_DIR/deploy")"
+if ! python3 "$DOCUMENT_TOOL" render "$BEFORE_XML" "$DEPLOY_XML" "${ASSIGNMENTS[@]}" >/dev/null; then
+  jq -n --argjson requested "$REQUESTED_JSON" --argjson before "$BEFORE_JSON" \
+    '{status:"blocked",reason_code:"render_failed",requested:$requested,before:$before,safe_to_write:true,deploy_id:null,blocking_issue:"Could not construct the preserved OmniChannel settings document."}'
+  exit 1
+fi
+
+DEPLOY_JSON=$(cd "$WORK_DIR/deploy" && sf project deploy start --target-org "$ORG" --source-dir "$DEPLOY_XML" --json 2>/dev/null || true)
+DEPLOY_SUCCESS=$(jq -r '.result.success // false' <<<"$DEPLOY_JSON" 2>/dev/null)
+DEPLOY_STATUS=$(jq -r '.result.status // ""' <<<"$DEPLOY_JSON" 2>/dev/null)
+DEPLOY_ID=$(jq -r '.result.id // ""' <<<"$DEPLOY_JSON" 2>/dev/null)
+if [ "$DEPLOY_SUCCESS" != "true" ] || [ "$DEPLOY_STATUS" = "SucceededPartial" ]; then
+  DEPLOY_ERROR=$(jq -r '.result.details.componentFailures // [] | if type == "array" then map(.problem) | join("; ") else .problem // "" end' <<<"$DEPLOY_JSON" 2>/dev/null)
+  if [ -z "$DEPLOY_ERROR" ] || [ "$DEPLOY_ERROR" = "null" ]; then
+    DEPLOY_ERROR=$(jq -r '.message // .result.errorMessage // "Unknown deploy error"' <<<"$DEPLOY_JSON" 2>/dev/null)
+  fi
+  jq -n --argjson requested "$REQUESTED_JSON" --argjson before "$BEFORE_JSON" --arg id "$DEPLOY_ID" --arg error "$DEPLOY_ERROR" \
+    '{status:"blocked",reason_code:"deploy_failed",requested:$requested,before:$before,after:null,safe_to_write:true,deploy_id:(if $id == "" then null else $id end),verification:null,blocking_issue:("OmniChannel settings deployment failed: " + $error)}'
+  exit 1
+fi
+
+if ! retrieve_settings "$WORK_DIR/after"; then
+  jq -n --argjson requested "$REQUESTED_JSON" --argjson before "$BEFORE_JSON" --arg id "$DEPLOY_ID" \
+    '{status:"blocked",reason_code:"verification_failed",requested:$requested,before:$before,after:null,safe_to_write:true,deploy_id:(if $id == "" then null else $id end),verification:null,blocking_issue:"Deployment succeeded, but post-deploy Settings:OmniChannel retrieval failed."}'
+  exit 1
+fi
+
+AFTER_XML="$(settings_path "$WORK_DIR/after")"
+if [ ! -f "$AFTER_XML" ] || ! AFTER_JSON=$(python3 "$DOCUMENT_TOOL" inspect "$AFTER_XML" 2>/dev/null); then
+  jq -n --argjson requested "$REQUESTED_JSON" --argjson before "$BEFORE_JSON" --arg id "$DEPLOY_ID" \
+    '{status:"blocked",reason_code:"verification_failed",requested:$requested,before:$before,after:null,safe_to_write:true,deploy_id:(if $id == "" then null else $id end),verification:null,blocking_issue:"Deployment succeeded, but the post-deploy settings document could not be inspected."}'
+  exit 1
+fi
+
+if ! values_match "$AFTER_JSON"; then
+  jq -n --argjson requested "$REQUESTED_JSON" --argjson before "$BEFORE_JSON" --argjson after "$AFTER_JSON" --arg id "$DEPLOY_ID" \
+    '{status:"blocked",reason_code:"verification_failed",requested:$requested,before:$before,after:$after,safe_to_write:true,deploy_id:(if $id == "" then null else $id end),verification:null,blocking_issue:"Deployment reported success, but one or more requested settings did not persist."}'
+  exit 1
+fi
+
+VERIFY_JSON=$(query_verification)
+if [ "$(jq -r '.complete' <<<"$VERIFY_JSON")" != "true" ]; then
+  jq -n --argjson requested "$REQUESTED_JSON" --argjson before "$BEFORE_JSON" --argjson after "$AFTER_JSON" --argjson verification "$VERIFY_JSON" --arg id "$DEPLOY_ID" \
+    '{status:"blocked",reason_code:"seed_incomplete",requested:$requested,before:$before,after:$after,safe_to_write:true,deploy_id:(if $id == "" then null else $id end),verification:$verification,manual_actions:[{id:"INSPECT_V2_SEED",title:"The settings persisted, but the V2 page and tab were not both observable. Inspect the platform seed hook before claiming readiness."}],blocking_issue:"Command Center V2 settings persisted, but seed verification is incomplete."}'
+  exit 1
+fi
+
+jq -n --argjson requested "$REQUESTED_JSON" --argjson before "$BEFORE_JSON" --argjson after "$AFTER_JSON" --argjson verification "$VERIFY_JSON" --arg id "$DEPLOY_ID" \
+  '{status:"configured",reason_code:"configured_and_verified",requested:$requested,before:$before,after:$after,safe_to_write:true,deploy_id:(if $id == "" then null else $id end),verification:$verification,manual_actions:[{id:"ASSIGN_V2_PERMISSION",title:"Assign CommandCenterForServiceUser to each intended supervisor, then verify with service-omni-command-center-analyze."}],blocking_issue:null}'

package/skills/service-omni-command-center-configure/scripts/settings_document.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""Inspect or safely mutate a retrieved OmniChannel Settings document."""
+
+import argparse
+import json
+import sys
+import xml.etree.ElementTree as ET
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+
+METADATA_NS = "http://soap.sforce.com/2006/04/metadata"
+FIELDS = (
+    "enableCommandCenterForServiceV2",
+    "enableConversationMonitoring",
+    "enableAgentSneakPeek",
+    "enableClientSneakPeek",
+    "enableWhisperMessaging",
+    "enableSkillsAndQueueActions",
+)
+
+
+def parse_document(path: Path) -> Tuple[ET.ElementTree, ET.Element]:
+    tree = ET.parse(path)
+    return tree, tree.getroot()
+
+
+def find_element(root: ET.Element, name: str) -> Optional[ET.Element]:
+    return root.find(f"{{{METADATA_NS}}}{name}")
+
+
+def inspect(path: Path) -> int:
+    _, root = parse_document(path)
+    settings = {}
+    for name in FIELDS:
+        element = find_element(root, name)
+        text = (element.text or "").strip().lower() if element is not None else ""
+        settings[name] = {
+            "present": element is not None,
+            "value": text == "true" if text in {"true", "false"} else None,
+        }
+    print(json.dumps({"settings": settings}, separators=(",", ":")))
+    return 0
+
+
+def render(source: Path, destination: Path, assignments: List[str]) -> int:
+    tree, root = parse_document(source)
+    requested = {}
+    for assignment in assignments:
+        if "=" not in assignment:
+            raise ValueError(f"Invalid assignment: {assignment}")
+        name, value = assignment.split("=", 1)
+        if name not in FIELDS:
+            raise ValueError(f"Unsupported setting: {name}")
+        if value not in {"true", "false"}:
+            raise ValueError(f"Invalid boolean for {name}: {value}")
+        requested[name] = value
+
+    if "enableCommandCenterForServiceV2" not in requested:
+        raise ValueError("enableCommandCenterForServiceV2 must be requested")
+
+    for name, value in requested.items():
+        element = find_element(root, name)
+        if element is None:
+            element = ET.SubElement(root, f"{{{METADATA_NS}}}{name}")
+        element.text = value
+
+    ET.register_namespace("", METADATA_NS)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    tree.write(destination, encoding="UTF-8", xml_declaration=True)
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    subparsers = parser.add_subparsers(dest="operation", required=True)
+
+    inspect_parser = subparsers.add_parser("inspect")
+    inspect_parser.add_argument("path", type=Path)
+
+    render_parser = subparsers.add_parser("render")
+    render_parser.add_argument("source", type=Path)
+    render_parser.add_argument("destination", type=Path)
+    render_parser.add_argument("assignments", nargs="+")
+
+    args = parser.parse_args()
+    try:
+        if args.operation == "inspect":
+            return inspect(args.path)
+        return render(args.source, args.destination, args.assignments)
+    except (ET.ParseError, OSError, ValueError) as error:
+        print(json.dumps({"error": str(error)}, separators=(",", ":")), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/service-omni-command-center-configure/scripts/tests/test_command_center_configure_contracts.py

@@ -0,0 +1,206 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+
+SKILLS_ROOT = Path(__file__).resolve().parents[3]
+SCRIPT = SKILLS_ROOT / "service-omni-command-center-configure/scripts/configure-and-report.sh"
+DOCUMENT_TOOL = SKILLS_ROOT / "service-omni-command-center-configure/scripts/settings_document.py"
+
+
+FAKE_SF = r"""#!/usr/bin/env bash
+set -euo pipefail
+args="$*"
+[ -z "${FAKE_CALL_LOG:-}" ] || printf '%s\n' "$args" >> "$FAKE_CALL_LOG"
+
+if [ "${1:-} ${2:-}" = "org display" ]; then
+  echo '{"status":0,"result":{"username":"fake@example.invalid"}}'
+  exit 0
+fi
+
+if [ "${1:-} ${2:-}" = "project retrieve" ]; then
+  mkdir -p force-app/main/default/settings
+  target=force-app/main/default/settings/OmniChannel.settings-meta.xml
+  if [ -f "$FAKE_STATE_DIR/deployed.xml" ]; then
+    cp "$FAKE_STATE_DIR/deployed.xml" "$target"
+  else
+    {
+      echo '<?xml version="1.0" encoding="UTF-8"?>'
+      echo '<OmniChannelSettings xmlns="http://soap.sforce.com/2006/04/metadata">'
+      echo '  <enableOmniChannel>true</enableOmniChannel>'
+      echo '  <unrelatedSetting>true</unrelatedSetting>'
+      if [ "${FAKE_API_PRESENT:-1}" = "1" ]; then
+        echo "  <enableCommandCenterForServiceV2>${FAKE_V2:-false}</enableCommandCenterForServiceV2>"
+        echo "  <enableConversationMonitoring>${FAKE_CONVERSATION:-false}</enableConversationMonitoring>"
+        echo "  <enableAgentSneakPeek>${FAKE_AGENT_PEEK:-false}</enableAgentSneakPeek>"
+        echo "  <enableClientSneakPeek>${FAKE_CLIENT_PEEK:-false}</enableClientSneakPeek>"
+        echo "  <enableWhisperMessaging>${FAKE_WHISPER:-false}</enableWhisperMessaging>"
+        echo "  <enableSkillsAndQueueActions>${FAKE_QUEUE_ACTIONS:-false}</enableSkillsAndQueueActions>"
+      fi
+      echo '</OmniChannelSettings>'
+    } > "$target"
+  fi
+  echo '{"status":0,"result":{"success":true}}'
+  exit 0
+fi
+
+if [ "${1:-} ${2:-}" = "project deploy" ]; then
+  if [ "${FAKE_DEPLOY_FAIL:-0}" = "1" ]; then
+    echo '{"status":1,"message":"simulated failure","result":{"success":false,"status":"Failed"}}'
+    exit 1
+  fi
+  source_path=""
+  while [ "$#" -gt 0 ]; do
+    if [ "$1" = "--source-dir" ]; then source_path="$2"; break; fi
+    shift
+  done
+  cp "$source_path" "$FAKE_STATE_DIR/deployed.xml"
+  touch "$FAKE_STATE_DIR/deployed"
+  echo '{"status":0,"result":{"success":true,"status":"Succeeded","id":"0AfFakeDeploy"}}'
+  exit 0
+fi
+
+if [ "${1:-} ${2:-}" = "data query" ]; then
+  if printf '%s' "$args" | grep -q 'FROM Organization'; then
+    if [ "${FAKE_PRODUCTION:-0}" = "1" ]; then
+      echo '{"status":0,"result":{"records":[{"IsSandbox":false,"TrialExpirationDate":null,"OrganizationType":"Enterprise Edition"}]}}'
+    else
+      echo '{"status":0,"result":{"records":[{"IsSandbox":true,"TrialExpirationDate":null,"OrganizationType":"Developer Edition"}]}}'
+    fi
+  elif printf '%s' "$args" | grep -q 'FROM FlexiPage'; then
+    if { [ -f "$FAKE_STATE_DIR/deployed" ] && [ "${FAKE_SEED_AFTER_DEPLOY:-1}" = "1" ]; } || [ "${FAKE_SEED_PRESENT:-0}" = "1" ]; then
+      echo '{"status":0,"result":{"records":[{"Id":"0M0Fake"}],"totalSize":1}}'
+    else
+      echo '{"status":0,"result":{"records":[],"totalSize":0}}'
+    fi
+  elif printf '%s' "$args" | grep -q 'FROM TabDefinition'; then
+    if { [ -f "$FAKE_STATE_DIR/deployed" ] && [ "${FAKE_TAB_AFTER_DEPLOY:-1}" = "1" ]; } || [ "${FAKE_TAB_PRESENT:-0}" = "1" ]; then
+      echo '{"status":0,"result":{"records":[{"Name":"standard-commandcenterforservicev2"}],"totalSize":1}}'
+    else
+      echo '{"status":0,"result":{"records":[],"totalSize":0}}'
+    fi
+  else
+    echo '{"status":0,"result":{"records":[],"totalSize":0}}'
+  fi
+  exit 0
+fi
+
+echo '{"status":1,"message":"unexpected fake sf invocation"}'
+exit 1
+"""
+
+
+def run_script(*args: str, **environment: str):
+    with tempfile.TemporaryDirectory(prefix="command-center-configure-") as directory:
+        root = Path(directory)
+        sf = root / "sf"
+        sf.write_text(FAKE_SF)
+        sf.chmod(0o755)
+        state = root / "state"
+        state.mkdir()
+        call_log = root / "calls.log"
+        env = dict(os.environ)
+        env.update(environment)
+        env["FAKE_STATE_DIR"] = str(state)
+        env["FAKE_CALL_LOG"] = str(call_log)
+        env["PATH"] = str(root) + os.pathsep + env.get("PATH", "")
+        result = subprocess.run(
+            ["bash", str(SCRIPT), *args],
+            capture_output=True,
+            text=True,
+            env=env,
+            cwd=str(SKILLS_ROOT),
+        )
+        calls = call_log.read_text() if call_log.exists() else ""
+        deployed = (state / "deployed.xml").read_text() if (state / "deployed.xml").exists() else ""
+        return result, calls, deployed
+
+
+class CommandCenterConfigureContracts(unittest.TestCase):
+    def test_script_and_python_syntax(self):
+        shell = subprocess.run(["bash", "-n", str(SCRIPT)], capture_output=True, text=True)
+        self.assertEqual(shell.returncode, 0, shell.stderr)
+        compile_result = subprocess.run(
+            ["python3", "-c", f"import ast, pathlib; ast.parse(pathlib.Path({str(DOCUMENT_TOOL)!r}).read_text())"],
+            capture_output=True,
+            text=True,
+            env={**os.environ, "PYTHONDONTWRITEBYTECODE": "1"},
+        )
+        self.assertEqual(compile_result.returncode, 0, compile_result.stderr)
+
+    def test_run_requires_apply_before_any_sf_call(self):
+        result, calls, _ = run_script("run", "test-org")
+        self.assertEqual(result.returncode, 1)
+        self.assertEqual(json.loads(result.stdout)["reason_code"], "apply_required")
+        self.assertEqual(calls, "")
+
+    def test_plan_reports_changes_without_deploying(self):
+        result, calls, _ = run_script("plan", "test-org")
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertEqual(json.loads(result.stdout)["status"], "action_needed")
+        self.assertNotIn("project deploy", calls)
+
+    def test_missing_platform_field_fails_before_deploy(self):
+        result, calls, _ = run_script("run", "test-org", "--apply", FAKE_API_PRESENT="0")
+        self.assertEqual(result.returncode, 1)
+        self.assertEqual(json.loads(result.stdout)["reason_code"], "platform_api_unavailable")
+        self.assertNotIn("project deploy", calls)
+
+    def test_production_org_is_refused(self):
+        result, calls, _ = run_script("run", "test-org", "--apply", FAKE_PRODUCTION="1")
+        self.assertEqual(result.returncode, 1)
+        self.assertEqual(json.loads(result.stdout)["reason_code"], "unsafe_target")
+        self.assertNotIn("project deploy", calls)
+
+    def test_run_preserves_unrelated_and_unspecified_settings(self):
+        result, calls, deployed = run_script(
+            "run",
+            "test-org",
+            "--apply",
+            "--agent-sneak-peek",
+            "true",
+        )
+        payload = json.loads(result.stdout)
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertEqual(payload["status"], "configured")
+        self.assertIn("project deploy", calls)
+        self.assertIn("<unrelatedSetting>true</unrelatedSetting>", deployed)
+        self.assertIn("<enableConversationMonitoring>false</enableConversationMonitoring>", deployed)
+        self.assertIn("<enableAgentSneakPeek>true</enableAgentSneakPeek>", deployed)
+        self.assertIn("<enableCommandCenterForServiceV2>true</enableCommandCenterForServiceV2>", deployed)
+
+    def test_already_ready_is_reused_without_deploy(self):
+        result, calls, _ = run_script(
+            "run",
+            "test-org",
+            "--apply",
+            FAKE_V2="true",
+            FAKE_SEED_PRESENT="1",
+            FAKE_TAB_PRESENT="1",
+        )
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertEqual(json.loads(result.stdout)["status"], "reused")
+        self.assertNotIn("project deploy", calls)
+
+    def test_persisted_settings_without_seed_are_blocked(self):
+        result, _, _ = run_script(
+            "run",
+            "test-org",
+            "--apply",
+            FAKE_SEED_AFTER_DEPLOY="0",
+            FAKE_TAB_AFTER_DEPLOY="0",
+        )
+        self.assertEqual(result.returncode, 1)
+        payload = json.loads(result.stdout)
+        self.assertEqual(payload["reason_code"], "seed_incomplete")
+        self.assertEqual(payload["after"]["settings"]["enableCommandCenterForServiceV2"]["value"], True)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)