@salesforce/afv-skills 1.8.0 → 1.9.1

package/skills/orchestrating-datacloud/UPSTREAM.md

@@ -0,0 +1,45 @@
+# Upstream Distillation Map for orchestrating-datacloud
+
+This file exists to make downstream maintenance easy without sacrificing sf-skills consistency.
+
+## Maintenance contract
+
+When upstream changes, do **not** copy blindly.
+
+Instead:
+1. review new upstream commits
+2. identify changed command behaviors, install patterns, or gotchas
+3. update sf-skills prompts and templates in a distilled form
+4. keep naming, attribution, and cross-skill boundaries consistent with sf-skills
+5. update this file with the new reviewed commit SHAs
+
+## High-priority upstream areas to re-check
+
+- installation / linking workflow for the community plugin
+- command counts and topic coverage
+- API-version guidance
+- known issues and bug-fix notes
+- live-tested command set
+- any new commands affecting Connect / Prepare / Harmonize / Segment / Act / Retrieve boundaries
+- connector-specific payload examples worth distilling into generic repo-safe examples
+- search-index / hybrid-search guidance and any command-surface changes around hybrid scoring or prefilter behavior
+- Ingestion API schema-upload flow, send-data examples, and problem-record guidance
+- unstructured-source setup differences between connection-level reruns, stream refreshes, and initial UI seeding
+- UI-only gaps where upstream introduces browser automation; validate before importing
+
+## Cross-skill boundary reminders
+
+Keep Data Cloud product work in `*-datacloud`, but do not blur into:
+- `observing-agentforce` for STDM/session tracing/parquet workflows
+- `querying-soql` for CRM SOQL-only tasks
+- `handling-sf-data` for CRM record seeding/cleanup
+- `generating-*` skills for CRM schema creation (custom objects, fields, validation rules, etc.)
+
+## Local helper files in this family
+
+- `references/plugin-setup.md`
+- `scripts/bootstrap-plugin.sh`
+- `scripts/verify-plugin.sh`
+- `assets/definitions/`
+
+These are sf-skills-owned conveniences and should evolve independently from upstream when that improves user experience.

package/skills/orchestrating-datacloud/assets/definitions/activation-target.template.json

@@ -0,0 +1,5 @@
+{
+  "developerName": "CRM_Target",
+  "displayName": "CRM Target",
+  "description": "Example activation target definition for a downstream destination"
+}

package/skills/orchestrating-datacloud/assets/definitions/activation.template.json

@@ -0,0 +1,7 @@
+{
+  "developerName": "High_Value_Customers_Activation",
+  "displayName": "High Value Customers Activation",
+  "description": "Example activation linking a published segment to a destination target",
+  "segmentName": "High_Value_Customers",
+  "activationTargetName": "CRM_Target"
+}

package/skills/orchestrating-datacloud/assets/definitions/calculated-insight.template.json

@@ -0,0 +1,7 @@
+{
+  "developerName": "Lifetime_Value",
+  "displayName": "Lifetime Value",
+  "description": "Example calculated insight over an order-style DMO",
+  "definitionType": "CALCULATED_METRIC",
+  "expression": "SELECT ssot__IndividualId__c, SUM(ssot__TotalAmount__c) AS total_spend FROM ssot__SalesOrder__dlm GROUP BY ssot__IndividualId__c"
+}

package/skills/orchestrating-datacloud/assets/definitions/data-action-target.template.json

@@ -0,0 +1,5 @@
+{
+  "developerName": "Webhook_Target",
+  "displayName": "Webhook Target",
+  "description": "Example data action target for downstream delivery"
+}

package/skills/orchestrating-datacloud/assets/definitions/data-action.template.json

@@ -0,0 +1,5 @@
+{
+  "developerName": "Notify_High_Value_Customer_System",
+  "displayName": "Notify High Value Customer System",
+  "description": "Example data action definition that uses a downstream data action target"
+}

package/skills/orchestrating-datacloud/assets/definitions/data-graph.template.json

@@ -0,0 +1,21 @@
+{
+  "developerName": "Customer_360_Graph",
+  "displayName": "Customer 360 Graph",
+  "description": "Example Data Graph rooted on a unified customer entity",
+  "sourceObject": {
+    "name": "UnifiedssotIndividualMain__dlm",
+    "type": "derived",
+    "fields": [
+      {
+        "name": "ssot__Id__c"
+      },
+      {
+        "name": "ssot__FirstName__c"
+      },
+      {
+        "name": "ssot__LastName__c"
+      }
+    ],
+    "relatedObjects": []
+  }
+}

package/skills/orchestrating-datacloud/assets/definitions/data-stream.template.json

@@ -0,0 +1,55 @@
+{
+  "name": "Customer_Stream",
+  "label": "Customer Stream",
+  "datasource": "SalesforceDotCom_Home",
+  "datastreamType": "CONNECTORSFRAMEWORK",
+  "connectorInfo": {
+    "connectorType": "SalesforceDotCom",
+    "connectorDetails": {
+      "name": "SalesforceDotCom_Home",
+      "sourceObject": "Custom_Object__c"
+    }
+  },
+  "dataLakeObjectInfo": {
+    "label": "Customer",
+    "name": "Customer__dll",
+    "category": "Profile",
+    "dataspaceInfo": [
+      {
+        "name": "Default"
+      }
+    ],
+    "dataLakeFieldInputRepresentations": [
+      {
+        "name": "Id",
+        "label": "Record ID",
+        "dataType": "Text",
+        "isPrimaryKey": true
+      },
+      {
+        "name": "External_Id_c",
+        "label": "External ID",
+        "dataType": "Text",
+        "isPrimaryKey": false
+      }
+    ]
+  },
+  "sourceFields": [
+    {
+      "name": "Id",
+      "dataType": "Text"
+    },
+    {
+      "name": "External_Id__c",
+      "dataType": "Text"
+    }
+  ],
+  "mappings": [],
+  "refreshConfig": {
+    "isAccelerationEnabled": true,
+    "refreshMode": "UPSERT",
+    "frequency": {
+      "frequencyType": "HOURLY"
+    }
+  }
+}

package/skills/orchestrating-datacloud/assets/definitions/dmo.template.json

@@ -0,0 +1,17 @@
+{
+  "developerName": "Customer_Profile__dlm",
+  "label": "Customer Profile",
+  "category": "Profile",
+  "fields": [
+    {
+      "name": "External_Id_c__c",
+      "label": "External ID",
+      "type": "Text"
+    },
+    {
+      "name": "Preferred_Tier_c__c",
+      "label": "Preferred Tier",
+      "type": "Text"
+    }
+  ]
+}

package/skills/orchestrating-datacloud/assets/definitions/identity-resolution.template.json

@@ -0,0 +1,30 @@
+{
+  "label": "Main",
+  "description": "Generic identity resolution ruleset using customer identifiers and contact points",
+  "configurationType": "individual",
+  "rulesetId": "main",
+  "doesRunAutomatically": false,
+  "matchRules": [
+    {
+      "label": "Exact Email",
+      "criteria": [
+        {
+          "entityName": "ssot__ContactPointEmail__dlm",
+          "fieldName": "ssot__EmailAddress__c",
+          "matchMethodType": "exactnormalized",
+          "caseSensitiveMatch": false,
+          "shouldMatchOnBlank": false
+        }
+      ]
+    }
+  ],
+  "reconciliationRules": [
+    {
+      "entityName": "ssot__Individual__dlm",
+      "ruleType": "lastupdated",
+      "shouldIgnoreEmptyValue": true,
+      "sources": [],
+      "fields": []
+    }
+  ]
+}

package/skills/orchestrating-datacloud/assets/definitions/mapping.template.json

@@ -0,0 +1,14 @@
+{
+  "sourceObjectName": "Customer__dll",
+  "targetObjectName": "Customer_Profile__dlm",
+  "fieldMappings": [
+    {
+      "sourceFieldName": "External_Id_c",
+      "targetFieldName": "External_Id_c__c"
+    },
+    {
+      "sourceFieldName": "Preferred_Tier_c",
+      "targetFieldName": "Preferred_Tier_c__c"
+    }
+  ]
+}

package/skills/orchestrating-datacloud/assets/definitions/relationship.template.json

@@ -0,0 +1,12 @@
+{
+  "relationships": [
+    {
+      "sourceObjectName": "Order_Header__dlm",
+      "targetObjectName": "ssot__Individual__dlm",
+      "cardinality": "ManyToOne",
+      "sourceFieldName": "Customer_ID_c__c",
+      "targetFieldName": "ssot__PartyId__c",
+      "relationshipOwner": "DataCloud"
+    }
+  ]
+}

package/skills/orchestrating-datacloud/assets/definitions/search-index.template.json

@@ -0,0 +1,9 @@
+{
+  "developerName": "Knowledge_Index",
+  "displayName": "Knowledge Index",
+  "description": "Example semantic search index for a structured or unstructured Data Cloud source",
+  "sourceObject": "KnowledgeArticleVersion__dlm",
+  "embeddingModel": "e5_large_v2",
+  "chunkingStrategy": "passage_extraction",
+  "similarityMetric": "COSINE"
+}

package/skills/orchestrating-datacloud/assets/definitions/segment.template.json

@@ -0,0 +1,16 @@
+{
+  "displayName": "High Value Customers",
+  "developerName": "High_Value_Customers",
+  "description": "Example segment built from a unified DMO",
+  "segmentType": "Dbt",
+  "includeDbt": {
+    "models": {
+      "models": [
+        {
+          "name": "UnifiedCustomers",
+          "sql": "SELECT ui.ssot__Id__c FROM UnifiedssotIndividualMain__dlm ui JOIN ssot__SalesOrder__dlm so ON ui.ssot__Id__c = so.ssot__IndividualId__c GROUP BY ui.ssot__Id__c HAVING SUM(so.ssot__TotalAmount__c) > 1000"
+        }
+      ]
+    }
+  }
+}

package/skills/orchestrating-datacloud/references/feature-readiness.md

@@ -0,0 +1,157 @@
+# Data Cloud Feature Readiness
+
+Use this guide when a Data Cloud command fails and you need to decide whether the issue is:
+- runtime / plugin setup
+- org authentication
+- product provisioning
+- feature gating
+- empty-but-enabled configuration
+- a bad table name or wrong probe
+
+The goal is to **detect first, classify second, and guide third** instead of blindly executing a command and surfacing a raw error.
+
+## Core principle
+
+Do **not** treat one failing command as proof that all of Data Cloud is unavailable.
+
+Different command families hit different backend surfaces. A failure in one area can coexist with successful read-only access in another.
+
+Examples:
+- `sf data360 doctor` checks the **search-index** endpoint only.
+- `sf data360 query describe` checks the **query** plane and requires a real DMO/DLO table name.
+- `sf data360 dmo list` checks a **catalog/listing** endpoint.
+- `sf data360 activation platforms` checks the **activation destination** surface.
+
+## Recommended first step
+
+Run the shared readiness classifier before mutation-heavy work:
+
+```bash
+node ~/.claude/skills/orchestrating-datacloud/scripts/diagnose-org.mjs -o myorg --json
+```
+
+For retrieve/query work, only add a table probe when you already know the table name is real:
+
+```bash
+node ~/.claude/skills/orchestrating-datacloud/scripts/diagnose-org.mjs -o myorg --phase retrieve --describe-table MyDMO__dlm --json
+```
+
+## Signal matrix
+
+| Signal | What it usually means | What to do next | What **not** to assume |
+|---|---|---|---|
+| `sf data360 man` fails | Runtime/plugin missing | Install or relink the community runtime | Do not debug org features yet |
+| `sf org display -o <org>` fails | Org auth missing | Re-authenticate the org | Do not blame Data Cloud |
+| `No results.` | Feature is reachable but currently empty | Continue with create/setup flow | Do not say the feature is disabled |
+| `This feature is not currently enabled for this user type or org: [CdpXxx]` | Specific module is gated for the current org/user | Guide the user to setup/provisioning/permission review for that module | Do not say the entire product is disabled |
+| `Couldn't find CDP tenant ID. Please enable CDP first.` | The **query** plane could not resolve a CDP tenant for that request | Re-check broader readiness with `data-space list`, `dmo list`, and `doctor`; then retry with a known table if appropriate | Do not treat this as universal proof that all Data Cloud endpoints are off |
+| `NOT_FOUND: DataModelEntity ... is not found` | The table name is not queryable in that org | Pick a real DMO/DLO from `dmo list`, `dlo list`, or `dmo get` | Do not say the whole query feature is unavailable |
+| `Request failed` | Generic endpoint failure or inconclusive response | Fall back to neighboring read-only probes | Do not stop after one generic failure |
+
+## High-signal feature gates
+
+### `CdpDataStreams`
+Typical impact:
+- `sf data360 data-stream list`
+- prepare / ingestion workflows
+
+Suggested guidance:
+- review Data Cloud Setup provisioning
+- review source connector readiness
+- confirm the user has the right Data Cloud permissions
+- for Salesforce CRM ingestion, confirm the connector/integration user has object + field read access in the source org
+
+### `CdpIdentityResolution`
+Typical impact:
+- `sf data360 identity-resolution list`
+- harmonize / unified profile workflows
+
+Suggested guidance:
+- review harmonization and identity-resolution entitlements
+- verify Data Cloud permission sets for the acting user
+- confirm upstream DLO/DMO work is already healthy before retrying IR
+
+### `CdpActivationTarget`
+Typical impact:
+- `sf data360 activation-target list`
+- downstream audience delivery setup
+
+Suggested guidance:
+- review Data Cloud activation permissions
+- review target/destination setup in Data Cloud Setup
+- confirm the org/edition actually exposes activation-target management for that user
+
+### `CdpActivationExternalPlatform`
+Typical impact:
+- `sf data360 activation platforms`
+- platform catalog for destinations such as ads or storage targets
+
+Suggested guidance:
+- review Activation Targets setup
+- review destination-specific authentication/configuration
+- check whether the org exposes additional toggles in **Data Cloud Setup → Feature Manager**
+
+### `CdpDataSpace`
+Typical impact:
+- `sf data360 data-space list`
+- core multi-space administration
+
+Suggested guidance:
+- review core Data Cloud provisioning and user access
+- confirm the user is intended to administer/view data spaces
+
+## What is usually **not** fully programmatic
+
+Do not promise a pure CLI flow for:
+- initial Data Cloud tenant provisioning
+- license assignment
+- every org-wide Data Cloud enablement step
+
+These commonly require Setup UI, provisioning, licensing, or account-level activation.
+
+## What is often programmatic **after** provisioning
+
+Once the org is properly provisioned, many workflows are programmatic through `sf data360`, including:
+- data-space listing / get / create / update
+- DMO catalog inspection and some DMO mutations
+- segment and calculated insight lifecycle operations
+- activation target and data action target operations
+- search-index lifecycle operations
+- hybrid search and related retrieve-plane workflows on newer runtime versions
+
+Exact coverage still depends on org entitlements and the user's permissions.
+
+## Known partial-automation gap
+
+Some external database connectors can be created via API while the corresponding data-stream creation flow still requires UI steps or org-specific browser automation.
+
+Practical guidance:
+- treat connection creation and stream creation as separate capability checks
+- do not assume a successful external connection create call means `data-stream create` will work for that connector
+- if the org relies on that path, guide the user toward manual UI creation or a locally validated Playwright/browser automation helper rather than promising a generic CLI-only workflow
+
+## User-facing guidance model
+
+When blocked, respond in this order:
+1. **Classify the failing surface** — runtime, auth, provisioning, feature gate, empty state, or bad table
+2. **Show the evidence** — the specific command + high-signal error text
+3. **Give the next setup step** — Data Cloud Setup, permissions, Feature Manager, source-object permissions, destination auth, etc.
+4. **Avoid false claims** — don't say "Data Cloud is off" unless multiple core probes support that conclusion
+
+## Setup guidance to point users toward
+
+Depending on the failing feature, guide users to review:
+- **Setup → Data Cloud Setup** for core provisioning / Get Started flow
+- **Standard Data Cloud permission sets** appropriate to the task (for example Architect/Admin vs activation-focused roles)
+- **Data Cloud Setup → Feature Manager** for org-specific toggles or beta features that are actually exposed there
+- **Source org permissions** for CRM ingestion users when streams/connectors depend on object/field access
+- **Activation target and destination authentication** when activation features are partially enabled but not usable yet
+
+## Skill author checklist
+
+Before telling the user a feature is unavailable:
+- [ ] Did I run a targeted probe for this phase?
+- [ ] Did I check at least one neighboring read-only probe?
+- [ ] Did I avoid treating `doctor` as a full product readiness check?
+- [ ] Did I avoid treating `query describe` as a universal tenant probe?
+- [ ] Did I tell the user exactly what setup area to review next?

package/skills/orchestrating-datacloud/references/plugin-setup.md

@@ -0,0 +1,140 @@
+# Data Cloud Community Plugin Setup
+
+The orchestrating-datacloud family uses a **community `sf data360` CLI runtime**. sf-skills does not vendor or fork that plugin.
+
+## Why this setup exists
+
+- keeps sf-skills focused on skills, prompts, docs, and templates
+- lets the upstream runtime continue to evolve independently
+- avoids MCP and keeps execution deterministic
+
+## Prerequisites
+
+- Node.js 18+
+- yarn
+- Salesforce CLI (`sf`)
+- git
+- a Data Cloud-enabled org authenticated with `sf org login web -a <alias>`
+
+## Recommended setup path
+
+The command examples below assume the skill is installed under `~/.claude/skills/` via the full Claude Code installer. If you are working from a cloned sf-skills repo instead, run the same scripts from that checkout path.
+
+If you use the Python installer, it can install this optional runtime for you:
+
+```bash
+python3 ~/.claude/sf-skills-install.py --with-datacloud-runtime
+```
+
+Or use the helper script directly:
+
+```bash
+bash ~/.claude/skills/orchestrating-datacloud/scripts/bootstrap-plugin.sh
+```
+
+By default it clones the plugin into `~/.sf-community-tools/datacloud/sf-cli-plugin-data360`, installs dependencies, compiles it, and links it into the local Salesforce CLI.
+
+## Manual setup
+
+```bash
+git clone https://github.com/Jaganpro/sf-cli-plugin-data360.git
+cd sf-cli-plugin-data360
+yarn install
+npx tsc
+node ~/.claude/skills/orchestrating-datacloud/scripts/generate-manifest.mjs .
+sf plugins link .
+```
+
+## Verification
+
+```bash
+sf data360 man
+bash ~/.claude/skills/orchestrating-datacloud/scripts/verify-plugin.sh
+bash ~/.claude/skills/orchestrating-datacloud/scripts/verify-plugin.sh myorg
+node ~/.claude/skills/orchestrating-datacloud/scripts/diagnose-org.mjs -o myorg --json
+```
+
+For newer command families such as `sf data360 query hybrid` and recent pagination fixes, update the community runtime to the latest upstream commit by re-running the bootstrap helper.
+
+`sf data360 doctor` is useful, but it is not the only readiness signal. On partially provisioned orgs it can fail even when other read-only Data Cloud commands still work. The helper script treats `doctor` as advisory and falls back to additional smoke checks.
+
+Use `diagnose-org.mjs` when you need phase-specific readiness classification instead of a simple pass/fail check. It helps distinguish:
+- empty-but-enabled modules
+- feature-gated modules
+- query-plane issues
+- runtime/auth failures
+
+## Output-noise tip
+
+When using linked community plugins, stderr can include warning noise. For normal usage, prefer:
+
+```bash
+sf data360 dmo list --all -o myorg 2>/dev/null
+sf data360 segment list -o myorg 2>/dev/null
+```
+
+## Troubleshooting
+
+### ESM auto-transpile warning
+
+If you see `Warning: @gthoppae/sf-cli-plugin-data360 is a linked ESM module and cannot be auto-transpiled`, generate the oclif command manifest:
+
+```bash
+node ~/.claude/skills/orchestrating-datacloud/scripts/generate-manifest.mjs ~/.sf-community-tools/datacloud/sf-cli-plugin-data360
+```
+
+This tells oclif to use pre-compiled output directly instead of attempting auto-transpilation. The `npx oclif manifest` alternative may fail on newer Node.js versions due to `@oclif/core` version mismatches.
+
+### Clone error references `gthoppae/sf-cli-plugin-data360`
+
+If the clone failure mentions `gthoppae/sf-cli-plugin-data360`, your local `~/.claude/sf-skills-install.py` copy is outdated. Refresh the installer first, then retry the optional runtime install:
+
+```bash
+python3 ~/.claude/sf-skills-install.py --force-update
+python3 ~/.claude/sf-skills-install.py --with-datacloud-runtime
+```
+
+Or rerun the latest installer directly from GitHub:
+
+```bash
+curl -sSL https://raw.githubusercontent.com/Jaganpro/sf-skills/main/tools/install.py | python3 - --with-datacloud-runtime
+```
+
+### Plugin not found after install
+
+If `sf` was installed globally (with `sudo`), the default data directory may be root-owned. Set `SF_DATA_DIR` in your shell profile:
+
+```bash
+export SF_DATA_DIR="${HOME}/.local/share/sf"
+```
+
+Then re-run `sf plugins link .` from the plugin directory, or re-run the bootstrap script.
+
+## What to do if the plugin is missing
+
+1. run the bootstrap script
+2. re-open your shell if `sf` plugin discovery is stale
+3. verify with `sf data360 man`
+4. only then start live Data Cloud work
+
+## Setup guidance reminder
+
+The runtime can help you **detect** missing capability, but it cannot fully replace Setup for:
+- initial Data Cloud provisioning / tenant creation
+- license assignment
+- every org-wide feature enablement step
+
+When a module is gated, guide users toward the right setup area instead of promising a fully programmatic enablement flow. See [feature-readiness.md](feature-readiness.md).
+
+## Scope reminder
+
+This setup is for the Data Cloud product family:
+- `orchestrating-datacloud`
+- `connecting-datacloud`
+- `preparing-datacloud`
+- `harmonizing-datacloud`
+- `segmenting-datacloud`
+- `activating-datacloud`
+- `retrieving-datacloud`
+
+For STDM/session tracing/parquet work, use `observing-agentforce` instead of this plugin-focused family.

package/skills/orchestrating-datacloud/scripts/bootstrap-plugin.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PLUGIN_REPO="${PLUGIN_REPO:-https://github.com/Jaganpro/sf-cli-plugin-data360.git}"
+BASE_DIR="${1:-${HOME}/.sf-community-tools/datacloud}"
+PLUGIN_DIR="${BASE_DIR}/sf-cli-plugin-data360"
+export SF_DATA_DIR="${SF_DATA_DIR:-${HOME}/.local/share/sf}"
+
+need() {
+  command -v "$1" >/dev/null 2>&1 || {
+    echo "Missing required command: $1" >&2
+    exit 1
+  }
+}
+
+need git
+need node
+need yarn
+need sf
+need npx
+
+mkdir -p "${BASE_DIR}"
+
+if [[ -d "${PLUGIN_DIR}/.git" ]]; then
+  echo "Updating existing plugin checkout: ${PLUGIN_DIR}"
+  git -C "${PLUGIN_DIR}" pull --ff-only
+else
+  echo "Cloning plugin into: ${PLUGIN_DIR}"
+  git clone "${PLUGIN_REPO}" "${PLUGIN_DIR}"
+fi
+
+cd "${PLUGIN_DIR}"
+
+echo "Installing dependencies..."
+yarn install
+
+echo "Compiling plugin..."
+npx tsc
+
+echo "Generating oclif command manifest..."
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+node "${SCRIPT_DIR}/generate-manifest.mjs" "${PLUGIN_DIR}"
+
+echo "Linking plugin into Salesforce CLI..."
+mkdir -p "${SF_DATA_DIR}"
+sf plugins link .
+
+echo "Verifying runtime..."
+sf data360 man >/dev/null
+
+echo "Done. Community Data Cloud runtime is linked."
+echo "Location: ${PLUGIN_DIR}"
+echo "Try: sf data360 man"