@salesforce/afv-skills 1.41.0 → 1.43.0

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

@@ -0,0 +1,101 @@
+# 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`.
+
+## The metadata type
+
+`ThunderbirdVoiceSettings` is a singleton settings type (extends `Metadata`),
+addressed by a fixed `fullName`:
+
+- **type (mdApiType)**: `ThunderbirdVoiceSettings`
+- **fullName**: `ThunderbirdVoice`
+
+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) |
+
+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.
+
+The type may expose other booleans (e.g. `enableCallRecRedaction`,
+`enableRealTimeStreamingRecording`, `enableSipRecording`). They are **out of scope** to
+*change*: the skill reads them only to preserve their existing values on the deployed
+file. It does, however, **echo them back unchanged** in a `preserved` block of the
+confirmation JSON — reporting a sibling's retrieved value is not the same as setting it,
+and compliance callers rely on that block for explicit "nothing else moved" assurance.
+No sibling is ever reported as changed.
+
+## Why the sf CLI, not raw SOAP
+
+`ThunderbirdVoiceSettings` is not a retrievable top-level type name, so it is easy to
+conclude "raw SOAP `updateMetadata()` is the only path." That is wrong. The generic
+**`Settings`** container type *is* in the sf CLI metadata registry, and its member is
+the mdApiType **without** the trailing `Settings` — i.e. `ThunderbirdVoice`. Retrieving
+and deploying through that container:
+
+- authenticates with the org's existing **`sf` login** — no browser session id /
+  access token is ever handled (raw SOAP on internal pc-rnd orgs rejects CLI OAuth
+  sessions on the SOAP endpoint, which is why a SOAP path there needs a browser sid);
+- lets us **retrieve first** to check the gate and snapshot sibling prefs, then deploy
+  a full file that preserves them;
+- gives a built-in **verify** step (round-trip retrieve).
+
+## The manifest
+
+`assets/package.xml` is the manifest template (the script generates it into a temp
+SFDX project). Two things matter:
+
+```xml
+<types><members>ThunderbirdVoice</members><name>Settings</name></types>
+<version>68.0</version>
+```
+
+- **member** = `ThunderbirdVoice` (mdApiType minus `Settings`), **name** = `Settings`.
+- **Pin the version to 68.0.** `ThunderbirdVoiceSettings` fields are only exposed at
+  API **v68.0 and above**, so anything below 68.0 returns the type empty/absent — the
+  fields simply are not in the schema at those versions. But do NOT reach for the CLI's
+  newest default either: a retrieve/deploy at a version **above the org's max supported
+  API** SILENTLY returns an empty result (no error), indistinguishable from "feature not
+  provisioned". 68.0 is the field-exposure floor and works on every org that has the
+  feature. (Verified sweep on thb-einstein, org max v68.0: v64/62/60 → "Settings type
+  'ThunderbirdVoice' is unknown"; v65/66/67 → type absent; v68 → fields present, deploy
+  round-trips; **v69 → success:true but files:[] — silent empty**.)
+
+## Sequence
+
+1. **Retrieve** `-x package.xml` → `force-app/main/default/settings/ThunderbirdVoice.settings-meta.xml`.
+2. **Gate check.** If the file is an empty self-closing `<ThunderbirdVoiceSettings/>`
+   (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.
+4. **Validate** with `deploy --dry-run` (never skip).
+5. **Deploy**.
+6. **Verify** by re-retrieving and confirming the org *returns* both `true`.
+
+## Distinguishing the two failure modes
+
+| Symptom | Cause | What to do |
+|---------|-------|------------|
+| Retrieve returns fields, deploy round-trips | Working as intended | done |
+| Retrieve returns an **empty** `<ThunderbirdVoiceSettings/>` | Org-perm gate off (feature not provisioned) | provision / Blacktab — not fixable via metadata |
+| Retrieve returns **no** settings file, or `Settings` type "unknown" | **API version too low** (< 68.0) | raise `--api-version` to 68.0+ |
+
+> The historical `FIELD_INTEGRITY_EXCEPTION: Property 'enableCallRecording' not valid
+> in version <N>` error was **a version problem, not a feature gate** — it appeared when
+> the request used an API version below 68.0. Bumping to v68.0+ resolves it. Do not
+> mistake it for an unprovisioned feature; distinguish the two with the retrieve gate
+> check above.
+
+## Auth
+
+`scripts/enable-recording-transcription.sh --target-org <alias>` uses the sf CLI's
+existing authentication for that alias (confirm with `sf org display -o <alias>`). No
+session id or access token is requested, handled, or printed.

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

@@ -0,0 +1,181 @@
+#!/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.
+#
+# 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.
+#
+# 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.
+#
+# Sequence: retrieve -> gate check -> flip the two target fields -> validate
+# (dry-run) -> deploy -> verify by round-trip -> print a JSON confirmation.
+#
+# Deps: sf, jq. (No curl, no session id.)
+#
+set -euo pipefail
+
+# 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
+# API SILENTLY returns an empty result (no error), which is indistinguishable from
+# "feature not provisioned". 68.0 works on every org that has the feature; do NOT
+# bump this default to a newer version unless you also cap it to the org's max.
+API_VERSION="68.0"
+TARGET_ORG=""
+DRY_RUN="false"
+
+# mdApiType ThunderbirdVoiceSettings -> package.xml member without the "Settings" suffix.
+MEMBER="ThunderbirdVoice"
+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).
+
+Usage:
+  enable-recording-transcription.sh --target-org <alias> [--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.
+Uses the org's sf login; no session id / access token is handled or printed.
+EOF
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --target-org) TARGET_ORG="$2"; shift 2 ;;
+    --api-version) API_VERSION="$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; }
+
+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)."
+[ -n "$TARGET_ORG" ] || fail "--target-org is required."
+
+# Guard the version floor deterministically. Require a full X.Y form so a bare
+# major like "68" can't end up as <version>68</version> in the manifest.
+printf '%s' "$API_VERSION" | grep -qE '^[0-9]+\.[0-9]+$' \
+  || fail "invalid --api-version '$API_VERSION' (expected X.Y, e.g. 68.0)."
+API_MAJOR="${API_VERSION%%.*}"
+[ "$API_MAJOR" -ge 68 ] || fail "--api-version must be >= 68.0 (ThunderbirdVoiceSettings is not exposed below v68.0). Got $API_VERSION."
+
+# --- scaffold an isolated SFDX project so the retrieve/deploy is self-contained
+WORKDIR="$(mktemp -d)"
+trap 'rm -rf "$WORKDIR"' EXIT
+sf project generate --name p --output-dir "$WORKDIR" >/dev/null 2>&1 \
+  || fail "could not scaffold a temporary SFDX project."
+PROJ="$WORKDIR/p"
+
+cat > "$PROJ/package.xml" <<EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<Package xmlns="http://soap.sforce.com/2006/04/metadata">
+    <types><members>${MEMBER}</members><name>Settings</name></types>
+    <version>${API_VERSION}</version>
+</Package>
+EOF
+
+SETTINGS_FILE="$PROJ/$SETTINGS_FILE_REL"
+
+# --- 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)."
+
+[ -f "$SETTINGS_FILE" ] || fail "retrieve returned no ${MEMBER}.settings-meta.xml — the Settings type was not returned at v${API_VERSION}. Two causes: (a) v${API_VERSION} is BELOW 68.0 (fields not yet exposed), or (b) v${API_VERSION} is ABOVE the org's max supported API version, which SILENTLY returns empty. Pin --api-version to the org's max (68.0 works on every org that has the feature)."
+
+# Gate check: an empty self-closing element means the org-perm gate
+# (orgHasNativeVoiceAllowed) is OFF — the feature is not provisioned. The fields
+# are only present when the gate is on.
+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"
+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."
+
+# --- 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
+# 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`.
+extract_preserved() { # $1 = settings xml file -> JSON array on stdout
+  { grep -oE '<[A-Za-z][A-Za-z0-9]*>(true|false)</[A-Za-z][A-Za-z0-9]*>' "$1" || true; } \
+    | sed -E 's#<([A-Za-z0-9]+)>([a-z]+)</[A-Za-z0-9]+>#\1 \2#' \
+    | { grep -vE '^(enableCallRecording|enableCallTranscription) ' || true; } \
+    | 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" \
+    '{
+      type: "ThunderbirdVoiceSettings",
+      fullName: "ThunderbirdVoice",
+      apiVersion: $apiVersion,
+      method: "sf project deploy (Settings/ThunderbirdVoice)",
+      headless: true,
+      preferences: [
+        { name: "enableCallRecording", enabled: true },
+        { name: "enableCallTranscription", enabled: true }
+      ],
+      preserved: $preserved,
+      status: $status
+    }'
+}
+
+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")"
+  exit 0
+fi
+
+# --- step 4: deploy ----------------------------------------------------------
+( cd "$PROJ" && sf project deploy start -x package.xml -o "$TARGET_ORG" --ignore-conflicts >/dev/null 2>&1 ) \
+  || fail "deploy failed after a successful dry-run."
+
+# --- step 5: verify by round-trip (do not trust "Succeeded") -----------------
+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."
+
+# 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")"

package/skills/data360-activate/README.md

@@ -1,38 +0,0 @@
-# data360-activate
-
-Activation and downstream delivery workflows for Salesforce Data Cloud.
-
-## Use this skill for
-
-- activations
-- activation targets
-- data actions
-- data action targets
-- downstream platform inspection before push
-
-## Example requests
-
-```text
-"Activate this segment to the downstream platform"
-"Show me what activation targets already exist"
-"Create a data action target for this integration"
-"Help me inspect why this activation is not ready"
-```
-
-## Common commands
-
-```bash
-sf data360 activation platforms -o myorg 2>/dev/null
-sf data360 activation-target list -o myorg 2>/dev/null
-sf data360 activation list -o myorg 2>/dev/null
-sf data360 data-action-target list -o myorg 2>/dev/null
-```
-
-## References
-
-- [SKILL.md](SKILL.md)
-- [../data360-orchestrate/assets/definitions/activation-target.template.json](../data360-orchestrate/assets/definitions/activation-target.template.json)
-- [../data360-orchestrate/assets/definitions/activation.template.json](../data360-orchestrate/assets/definitions/activation.template.json)
-- [../data360-orchestrate/assets/definitions/data-action-target.template.json](../data360-orchestrate/assets/definitions/data-action-target.template.json)
-- [../data360-orchestrate/assets/definitions/data-action.template.json](../data360-orchestrate/assets/definitions/data-action.template.json)
-- [../data360-orchestrate/references/plugin-setup.md](../data360-orchestrate/references/plugin-setup.md)

package/skills/data360-activate/SKILL.md

@@ -1,127 +0,0 @@
----
-name: data360-activate
-description: "Salesforce Data Cloud Act phase. Use this skill when the user manages activations, activation targets, data actions, or downstream delivery of Data Cloud audiences and data. TRIGGER when: user manages activations, activation targets, data actions, or downstream delivery of Data Cloud audiences and data. DO NOT TRIGGER when: the task is segment creation (use data360-segment), data retrieval/search work (use data360-query), or STDM/session tracing (use agentforce-observe)."
-metadata:
-  cliTools:
-    - tool: ["node"]
-      semver: ">=18.0.0"
-    - tool: ["sf"]
-      semver: ">=2.0.0"
-  relatedSkills:
-    - "agentforce-observe"
-    - "data360-connect"
-    - "data360-orchestrate"
-    - "data360-prepare"
-    - "data360-query"
-    - "data360-segment"
-  version: "1.0"
-  domains: ["Data 360"]
----
-
-# data360-activate: Data Cloud Act Phase
-
-Use this skill when the user needs **downstream delivery work**: activations, activation targets, data actions, or pushing Data Cloud outputs into other systems.
-
-## When This Skill Owns the Task
-
-Use `data360-activate` when the work involves:
-- `sf data360 activation *`
-- `sf data360 activation-target *`
-- `sf data360 data-action *`
-- `sf data360 data-action-target *`
-- verifying downstream delivery setup
-
-Delegate elsewhere when the user is:
-- still building the audience or insight → [data360-segment](../data360-segment/SKILL.md)
-- exploring query/search or search indexes → [data360-query](../data360-query/SKILL.md)
-- setting up base connections or ingestion → [data360-connect](../data360-connect/SKILL.md), [data360-prepare](../data360-prepare/SKILL.md)
-
----
-
-## Required Context to Gather First
-
-Ask for or infer:
-- target org alias
-- destination platform or downstream system
-- whether the segment already exists and is published
-- whether the user needs create, inspect, update, or delete
-- whether the task is activation-focused or data-action-focused
-
----
-
-## Core Operating Rules
-
-- Verify the upstream segment or insight is healthy before creating downstream delivery assets.
-- Run the shared readiness classifier before mutating activation assets: `node ../data360-orchestrate/scripts/diagnose-org.mjs -o <org> --phase act --json`.
-- Inspect available platforms and targets before mutating activation setup.
-- Keep destination definitions deterministic and reusable where possible.
-- Treat downstream credential and platform constraints as separate validation concerns.
-- Prefer read-only inspection first when the destination state is unclear.
-
----
-
-## Recommended Workflow
-
-### 1. Classify readiness for act work
-```bash
-node ../data360-orchestrate/scripts/diagnose-org.mjs -o <org> --phase act --json
-```
-
-### 2. Inspect destinations first
-```bash
-sf data360 activation platforms -o <org> 2>/dev/null
-sf data360 activation-target list -o <org> 2>/dev/null
-sf data360 data-action-target list -o <org> 2>/dev/null
-```
-
-### 3. Create the destination before the activation
-```bash
-sf data360 activation-target create -o <org> -f target.json 2>/dev/null
-sf data360 data-action-target create -o <org> -f target.json 2>/dev/null
-```
-
-### 4. Create the activation or data action
-```bash
-sf data360 activation create -o <org> -f activation.json 2>/dev/null
-sf data360 data-action create -o <org> -f action.json 2>/dev/null
-```
-
-### 5. Verify downstream readiness
-```bash
-sf data360 activation list -o <org> 2>/dev/null
-sf data360 activation data -o <org> --name <activation> 2>/dev/null
-```
-
----
-
-## High-Signal Gotchas
-
-- Activation design depends on a healthy published upstream segment.
-- Destination configuration usually comes before activation creation.
-- Downstream credential and platform constraints may live outside the Data Cloud CLI alone.
-- Read-only inspection is the safest first move when the destination setup is unclear.
-- `CdpActivationTarget` or `CdpActivationExternalPlatform` means the activation surface is gated for the current org/user; guide the user toward activation setup, permissions, and destination configuration instead of retrying blindly.
-
----
-
-## Output Format
-
-```text
-Act task: <activation / activation-target / data-action / data-action-target>
-Destination: <platform or target>
-Target org: <alias>
-Artifacts: <definition files / commands>
-Verification: <listed / created / blocked>
-Next step: <destination validation or downstream testing>
-```
-
----
-
-## References
-
-- [../data360-orchestrate/assets/definitions/activation-target.template.json](../data360-orchestrate/assets/definitions/activation-target.template.json)
-- [../data360-orchestrate/assets/definitions/activation.template.json](../data360-orchestrate/assets/definitions/activation.template.json)
-- [../data360-orchestrate/assets/definitions/data-action-target.template.json](../data360-orchestrate/assets/definitions/data-action-target.template.json)
-- [../data360-orchestrate/assets/definitions/data-action.template.json](../data360-orchestrate/assets/definitions/data-action.template.json)
-- [../data360-orchestrate/references/plugin-setup.md](../data360-orchestrate/references/plugin-setup.md)
-- [../data360-orchestrate/references/feature-readiness.md](../data360-orchestrate/references/feature-readiness.md)

package/skills/data360-connect/README.md

@@ -1,57 +0,0 @@
-# data360-connect
-
-Connection and connector workflows for Salesforce Data Cloud.
-
-## Use this skill for
-
-- listing available connector types
-- inspecting configured connections
-- testing a connection
-- browsing source objects, databases, fields, and uploaded schemas
-- preparing connector JSON for Snowflake, SharePoint Unstructured, and Ingestion API sources
-- preparing for stream creation
-
-## Key reminders
-
-- `connection list` requires `--connector-type`
-- `connection test` may need `--connector-type` for non-Salesforce name resolution
-- use `connection schema-upsert` after creating an Ingestion API connector
-- start with inspection before mutation
-- use `2>/dev/null` to suppress linked-plugin warning noise
-- some connector types can be created by API while downstream stream creation still requires UI flow
-
-## Example requests
-
-```text
-"Show me which Data Cloud connections already exist in this org"
-"Test my Snowflake Data Cloud connection"
-"What source objects are available on this Salesforce connector?"
-"Help me create an Ingestion API connector and upload its schema"
-"Set up a SharePoint Unstructured connection for document ingestion"
-```
-
-## Common commands
-
-```bash
-sf data360 connection connector-list -o myorg 2>/dev/null
-sf data360 connection list -o myorg --connector-type SalesforceDotCom 2>/dev/null
-sf data360 connection get -o myorg --name SalesforceDotCom_Home 2>/dev/null
-sf data360 connection test -o myorg --name Snowflake_Demo --connector-type SNOWFLAKE 2>/dev/null
-sf data360 connection schema-get -o myorg --name <connector-id> 2>/dev/null
-sf data360 connection create -o myorg -f examples/connections/heroku-postgres.json 2>/dev/null
-sf data360 connection schema-upsert -o myorg --name <connector-id> -f examples/connections/ingest-api-schema.json 2>/dev/null
-```
-
-## Example payloads
-
-- [examples/connections/heroku-postgres.json](examples/connections/heroku-postgres.json)
-- [examples/connections/redshift.json](examples/connections/redshift.json)
-- [examples/connections/sharepoint-unstructured.json](examples/connections/sharepoint-unstructured.json)
-- [examples/connections/snowflake-connection.json](examples/connections/snowflake-connection.json)
-- [examples/connections/ingest-api-connection.json](examples/connections/ingest-api-connection.json)
-- [examples/connections/ingest-api-schema.json](examples/connections/ingest-api-schema.json)
-
-## References
-
-- [SKILL.md](SKILL.md)
-- [../data360-orchestrate/references/plugin-setup.md](../data360-orchestrate/references/plugin-setup.md)

package/skills/data360-connect/SKILL.md

@@ -1,163 +0,0 @@
----
-name: data360-connect
-description: "Salesforce Data Cloud Connect phase. Use this skill when the user manages Data Cloud connections, connectors, or sets up a new source system. TRIGGER when: user manages Data Cloud connections, connectors, connector metadata, tests a connection, browses source objects or databases, or sets up a new source system. DO NOT TRIGGER when: the task is about data streams or DLOs (use data360-prepare), DMOs or identity resolution (use data360-harmonize), retrieval/search (use data360-query), or STDM telemetry (use agentforce-observe)."
-metadata:
-  cliTools:
-    - tool: ["node"]
-      semver: ">=18.0.0"
-    - tool: ["sf"]
-      semver: ">=2.0.0"
-  relatedSkills:
-    - "agentforce-observe"
-    - "data360-harmonize"
-    - "data360-orchestrate"
-    - "data360-prepare"
-    - "data360-query"
-  version: "1.0"
-  domains: ["Data 360"]
----
-
-# data360-connect: Data Cloud Connect Phase
-
-Use this skill when the user needs **source connection work**: connector discovery, connection metadata, connection testing, source-object browsing, connector schema inspection, or connector-specific setup payloads for external sources.
-
-## When This Skill Owns the Task
-
-Use `data360-connect` when the work involves:
-- `sf data360 connection *`
-- connector catalog inspection
-- connection creation, update, test, or delete
-- browsing source objects, fields, databases, or schemas
-- identifying connector types already in use
-- preparing connector definitions for Snowflake, SharePoint Unstructured, or Ingestion API sources
-
-Delegate elsewhere when the user is:
-- creating data streams or DLOs → [data360-prepare](../data360-prepare/SKILL.md)
-- creating DMOs, mappings, IR rulesets, or data graphs → [data360-harmonize](../data360-harmonize/SKILL.md)
-- writing Data Cloud SQL or search-index workflows → [data360-query](../data360-query/SKILL.md)
-
----
-
-## Required Context to Gather First
-
-Ask for or infer:
-- target org alias
-- connector type or source system
-- whether the user wants inspection only or live mutation
-- connection name or ID if one already exists
-- whether credentials are already configured outside the CLI
-- whether the user also expects stream creation right after connection setup
-- whether the source is a database, an unstructured document source, or an Ingestion API feed
-
----
-
-## Core Operating Rules
-
-- Verify the plugin runtime first; see [../data360-orchestrate/references/plugin-setup.md](../data360-orchestrate/references/plugin-setup.md).
-- Run the shared readiness classifier before mutating connections: `node ../data360-orchestrate/scripts/diagnose-org.mjs -o <org> --phase connect --json`.
-- Prefer read-only discovery before connection creation.
-- Suppress linked-plugin warning noise with `2>/dev/null` for standard usage.
-- Remember that `connection list` requires `--connector-type`.
-- For `connection test`, pass `--connector-type` when resolving a non-Salesforce connection by name.
-- Discover existing connector types from streams first when the org is unfamiliar.
-- Use curated example payloads before inventing connector-specific credentials or parameters.
-- For connector types outside the curated examples, inspect a known-good UI-created connection via REST before building JSON.
-- Do not promise API-based stream creation for every connector type just because connection creation succeeds.
-
----
-
-## Recommended Workflow
-
-### 1. Classify readiness for connect work
-```bash
-node ../data360-orchestrate/scripts/diagnose-org.mjs -o <org> --phase connect --json
-```
-
-### 2. Discover connector types
-```bash
-sf data360 connection connector-list -o <org> 2>/dev/null
-sf data360 data-stream list -o <org> 2>/dev/null
-```
-
-### 3. Inspect connections by type
-```bash
-sf data360 connection list -o <org> --connector-type SalesforceDotCom 2>/dev/null
-sf data360 connection list -o <org> --connector-type REDSHIFT 2>/dev/null
-sf data360 connection list -o <org> --connector-type SNOWFLAKE 2>/dev/null
-```
-
-### 4. Inspect a specific connection or uploaded schema
-```bash
-sf data360 connection get -o <org> --name <connection> 2>/dev/null
-sf data360 connection objects -o <org> --name <connection> 2>/dev/null
-sf data360 connection fields -o <org> --name <connection> 2>/dev/null
-sf data360 connection schema-get -o <org> --name <connection-id> 2>/dev/null
-```
-
-### 5. Test or create only after discovery
-```bash
-sf data360 connection test -o <org> --name <connection> --connector-type <type> 2>/dev/null
-sf data360 connection create -o <org> -f connection.json 2>/dev/null
-```
-
-### 6. Start from curated example payloads for external connectors
-Use the phase-owned examples before inventing a payload from scratch:
-- `examples/connections/heroku-postgres.json`
-- `examples/connections/redshift.json`
-- `examples/connections/sharepoint-unstructured.json`
-- `examples/connections/snowflake-connection.json`
-- `examples/connections/ingest-api-connection.json`
-- `examples/connections/ingest-api-schema.json`
-
-Typical Ingestion API setup flow:
-```bash
-sf data360 connection create -o <org> -f examples/connections/ingest-api-connection.json 2>/dev/null
-sf data360 connection schema-upsert -o <org> --name <connector-id> -f examples/connections/ingest-api-schema.json 2>/dev/null
-sf data360 connection schema-get -o <org> --name <connector-id> 2>/dev/null
-```
-
-### 7. Discover payload fields for unknown connector types
-Create one in the UI, then inspect it directly:
-```bash
-sf api request rest "/services/data/v66.0/ssot/connections/<id>" -o <org>
-```
-
----
-
-## High-Signal Gotchas
-
-- `connection list` has no true global "list all" mode; query by connector type.
-- The connector catalog name and connection connector type are not always the same label.
-- `connection test` may need `--connector-type` for name resolution when the source is not a default Salesforce connector.
-- An empty connection list usually means "enabled but not configured yet", not "feature disabled".
-- Heroku Postgres, Redshift, Snowflake, SharePoint Unstructured, and Ingestion API all use different credential and parameter shapes; reuse the curated examples instead of guessing.
-- SharePoint Unstructured uses `clientId`, `clientSecret`, and `tokenEndpoint` in the `credentials` array and does not require a `parameters` array.
-- Snowflake uses key-pair auth and can often be created through the API, but downstream stream creation can still remain UI-only.
-- Ingestion API connector setup is incomplete until `connection schema-upsert` has uploaded the object schema.
-- Some external connector credential setup still depends on UI-side configuration or external-system permissions.
-
----
-
-## Output Format
-
-```text
-Connect task: <inspect / create / test / update>
-Connector type: <SalesforceDotCom / REDSHIFT / SNOWFLAKE / SPUnstructuredDocument / IngestApi / ...>
-Target org: <alias>
-Commands: <key commands run>
-Verification: <passed / partial / blocked>
-Next step: <prepare phase or connector follow-up>
-```
-
----
-
-## References
-
-- [examples/connections/heroku-postgres.json](examples/connections/heroku-postgres.json)
-- [examples/connections/redshift.json](examples/connections/redshift.json)
-- [examples/connections/sharepoint-unstructured.json](examples/connections/sharepoint-unstructured.json)
-- [examples/connections/snowflake-connection.json](examples/connections/snowflake-connection.json)
-- [examples/connections/ingest-api-connection.json](examples/connections/ingest-api-connection.json)
-- [examples/connections/ingest-api-schema.json](examples/connections/ingest-api-schema.json)
-- [../data360-orchestrate/references/plugin-setup.md](../data360-orchestrate/references/plugin-setup.md)
-- [../data360-orchestrate/references/feature-readiness.md](../data360-orchestrate/references/feature-readiness.md)