@salesforce/afv-skills 1.22.0 → 1.24.0

package/skills/observing-agentforce/references/stdm-schema.md

@@ -1,189 +0,0 @@
-# STDM Schema Reference
-
-Data Model Object (DMO) schemas, field mappings, query patterns, and data quality notes for the Session Trace Data Model.
-
----
-
-## Data Hierarchy
-
-```
-AiAgentSession (1)
-+-- AiAgentSessionParticipant (N)       -- agent planner IDs and user IDs linked to this session
-+-- AiAgentInteraction (N)              -- one per conversational turn
-|   +-- AiAgentInteractionMessage (N)   -- user and agent messages
-|   +-- AiAgentInteractionStep (N)      -- internal steps (LLM, actions)
-+-- AiAgentMoment (N)                   -- one per intent/moment in the session
-|   +-- AiAgentMomentInteraction (N)    -- junction: links moments to interactions
-|   +-- AiAgentTagAssociation (N)       -- junction: links moments to tags (quality scores)
-|       +-- AiAgentTag (1)              -- score value (1-5)
-|           +-- AiAgentTagDefinition (1)-- tag type definition
-AiRetrieverQualityMetric (N)            -- RAG quality scores, linked via gateway request ID
-```
-
-**Quality score join chain:** `AiAgentTagAssociation` (FK `AiAgentMomentId` + FK `AiAgentTagId`) -> `AiAgentTag.Value` (1-5 integer). The `AssociationReasonText` field contains the LLM-generated reasoning for the score.
-
----
-
-## Key Fields
-
-### AiAgentSession (`ssot__AiAgentSession__dlm`)
-- `ssot__Id__c` -- Session ID
-- `ssot__StartTimestamp__c` / `ssot__EndTimestamp__c` -- Session timing -> `session.duration_ms`
-- `ssot__AiAgentChannelType__c` -- Channel -> `session.channel`
-- `ssot__AiAgentSessionEndType__c` -- How the session ended: `USER_ENDED`, `AGENT_ENDED`, or null -> `session.end_type`
-- `ssot__VariableText__c` -- Final variable snapshot for the session -> `session.session_variables`
-
-### AiAgentSessionParticipant (`ssot__AiAgentSessionParticipant__dlm`)
-- `ssot__AiAgentSessionId__c` -- Session this participant belongs to
-- `ssot__AiAgentApiName__c` -- API name of the agent (primary filter field -- no SOQL needed)
-- `ssot__ParticipantId__c` -- GenAiPlannerDefinition ID (key prefix `16j`) for agents, `005...` for users. May be 15-char or 18-char.
-
-### AiAgentInteraction (`ssot__AiAgentInteraction__dlm`)
-- `ssot__TopicApiName__c` -- Subagent/skill that handled this turn (API field name `TopicApiName` maps to Agent Script subagent) -> `turn.topic`
-- `ssot__StartTimestamp__c` / `ssot__EndTimestamp__c` -- Turn timing -> `turn.duration_ms`
-- `ssot__TelemetryTraceId__c` -- Distributed tracing ID -> `turn.telemetry_trace_id`
-
-### AiAgentInteractionMessage (`ssot__AiAgentInteractionMessage__dlm`)
-- `ssot__AiAgentInteractionMessageType__c` -- `Input` (user) or `Output` (agent) -> `message.message_type`
-- `ssot__ContentText__c` -- Message text -> `message.text`
-
-### AiAgentInteractionStep (`ssot__AiAgentInteractionStep__dlm`)
-- `ssot__AiAgentInteractionStepType__c` -- `TOPIC_STEP`, `LLM_STEP`, `ACTION_STEP`, `SESSION_END`, `TRUST_GUARDRAILS_STEP` -> `step.step_type`
-- `ssot__Name__c` -- Step or action name -> `step.name`
-- `ssot__ErrorMessageText__c` -- Error text (null if none) -> `step.error`
-- `ssot__InputValueText__c` / `ssot__OutputValueText__c` -- Input/output data -> `step.input` / `step.output`
-- `ssot__PreStepVariableText__c` / `ssot__PostStepVariableText__c` -- Variable snapshots -> `step.pre_vars` / `step.post_vars`
-- `ssot__GenerationId__c` -- Links to `GenAIGeneration__dlm` -> `step.generation_id` (non-null on LLM_STEP)
-- `ssot__GenAiGatewayRequestId__c` -- Links to `GenAIGatewayRequest__dlm` -> `step.gateway_request_id` (non-null on LLM_STEP)
-
-### Einstein Audit & Feedback DMOs (joined via `getLlmStepDetails()`)
-
-**`GenAIGeneration__dlm`** -- LLM generation records:
-- `generationId__c` -- Join key to `ssot__GenerationId__c` on the step DMO
-- `responseText__c` -- The full LLM response text -> `LlmStepDetail.llm_response`
-
-**`GenAIGatewayRequest__dlm`** -- Raw gateway requests sent to the LLM:
-- `gatewayRequestId__c` -- Join key to `ssot__GenAiGatewayRequestId__c` on the step DMO
-- `prompt__c` -- Full prompt text including system instructions -> `LlmStepDetail.prompt`
-
-These two DMOs are only populated when Einstein Audit & Feedback is enabled in the org's Data Cloud setup.
-
-### AiAgentMoment (`ssot__AiAgentMoment__dlm`)
-
-Each moment represents a distinct user intent within a session. One session may have multiple moments.
-- `ssot__Id__c` -- Moment ID
-- `ssot__AiAgentSessionId__c` -- FK to AiAgentSession
-- `ssot__StartTimestamp__c` / `ssot__EndTimestamp__c` -- Moment timing -> `MomentData.duration_ms`
-- `ssot__RequestSummaryText__c` -- LLM-generated summary of user intent -> `MomentData.request_summary`
-- `ssot__ResponseSummaryText__c` -- LLM-generated summary of agent response -> `MomentData.response_summary`
-- `ssot__AiAgentApiName__c` -- Agent API name that handled this moment
-- `ssot__AiAgentVersionApiName__c` -- Agent version API name
-
-### AiAgentMomentInteraction (`ssot__AiAgentMomentInteraction__dlm`)
-
-Links moments to the interactions (turns) they span. One moment may cover multiple turns.
-- `ssot__Id__c` -- Junction record ID
-- `ssot__AiAgentMomentId__c` -- FK to AiAgentMoment
-- `ssot__AiAgentInteractionId__c` -- FK to AiAgentInteraction
-- `ssot__StartTimestamp__c` -- When this moment-interaction link was created
-
-### AiAgentTagAssociation (`ssot__AiAgentTagAssociation__dlm`)
-
-The key junction table for quality scores. Links a moment to a tag (score 1-5) with LLM reasoning.
-- `ssot__Id__c` -- Association ID
-- `ssot__AiAgentMomentId__c` -- FK to AiAgentMoment
-- `ssot__AiAgentTagId__c` -- FK to AiAgentTag (join to get the score value)
-- `ssot__AiAgentSessionId__c` -- FK to AiAgentSession (denormalized for efficient filtering)
-- `ssot__AiAgentInteractionId__c` -- FK to AiAgentInteraction
-- `ssot__AiAgentTagDefinitionAssociationId__c` -- FK to TagDefinitionAssociation
-- `ssot__AssociationReasonText__c` -- LLM-generated reasoning for the quality score -> `MomentData.quality_reasoning`
-- `ssot__IsPassed__c` -- Whether the moment passed quality threshold
-
-Quality score query: `TagAssociation JOIN Tag ON TagId -> Tag.Value` gives the 1-5 integer score per moment.
-
-### AiAgentTag (`ssot__AiAgentTag__dlm`)
-
-Contains the 5 quality score levels (1-5). Each tag has a numeric value.
-- `ssot__Id__c` -- Tag ID
-- `ssot__AiAgentTagDefinitionId__c` -- FK to tag definition
-- `ssot__Value__c` -- Score value (e.g. "1", "2", "3", "4", "5") -> `MomentData.quality_score`
-- `ssot__Description__c` -- Score description (null in current orgs)
-- `ssot__IsActive__c` -- Whether this tag is active
-
-### AiAgentTagDefinition (`ssot__AiAgentTagDefinition__dlm`)
-
-Defines tag categories per agent. Each agent gets its own tag definition.
-- `ssot__Id__c` -- Tag Definition ID
-- `ssot__Name__c` -- Display name (e.g. "Optimization Request Category")
-- `ssot__DeveloperName__c` -- API name (e.g. "AIE_Request_Category_MyServiceAgent")
-- `ssot__DataType__c` -- Data type (e.g. "Text")
-- `ssot__EngineType__c` -- Engine that generates the tags
-- `ssot__Status__c` -- Definition status
-
-### AiRetrieverQualityMetric (`ssot__AiRetrieverQualityMetric__dlm`)
-
-Per-retrieval quality metrics for agents using knowledge retrieval. Links to sessions via gateway request ID.
-- `ssot__Id__c` -- Metric ID
-- `ssot__AiGatewayRequestId__c` -- FK to GenAIGatewayRequest
-- `ssot__AiRetrieverRequestId__c` -- Retriever request ID
-- `ssot__RetrieverApiName__c` -- API name of the retriever
-- `ssot__UserUtteranceText__c` -- User utterance that triggered retrieval
-- `ssot__AgentGeneratedResponseText__c` -- Agent response text
-- `ssot__FaithfulnessRelevancyScoreNumber__c` -- Faithfulness score (0-1)
-- `ssot__AnswerRelevancyScoreNumber__c` -- Answer relevance score (0-1)
-- `ssot__ContextPrecisionScoreNumber__c` -- Context precision score (0-1)
-
-Only populated when the agent uses knowledge retrieval actions. May have 0 rows if the agent has no RAG actions.
-
----
-
-## TRUST_GUARDRAILS_STEP
-
-A safety/compliance step that measures whether the agent's response followed its instructions:
-- `step.name` is typically `InstructionAdherence`
-- `step.output` is a Python-style dict string (not JSON). Actual format:
-  ```
-  {'name': 'InstructionAdherence', 'value': 'HIGH', 'explanation': 'This response adheres to the assigned instructions.'}
-  ```
-  Check for adherence by searching for `'value': 'LOW'` in the output string.
-- `step.input` contains the raw `input_text` and `output_text` that were evaluated
-- `step.error` may contain the literal string `"None"` (not a real error)
-- Does **not** count toward `action_error_count`
-
----
-
-## Data Quality Notes
-
-**`NOT_SET` sentinel.** Data Cloud uses `"NOT_SET"` for null/absent values. `AgentforceOptimizeService` strips this sentinel -- any field returning `null` in the JSON should be treated as absent.
-
-**`TRUST_GUARDRAILS_STEP` error field.** May have the Python string `"None"` in the error field. This is **not** a real error -- treat it as absent. `action_error_count` is only incremented for `ACTION_STEP` errors.
-
-**Null `end_time` / `duration_ms`.** Sessions and turns may have `null` for `end_time` when no session-end event was recorded. This is common and does not indicate a problem.
-
-**`LLM_STEP` input/output format.** The `input` and `output` fields on `LLM_STEP` contain raw Python dict strings (the internal LlamaIndex representation), not valid JSON. Do not attempt to `JSON.parse()` these values. Only `ACTION_STEP` input/output is structured JSON.
-
-**Participant ID format inconsistency.** The `ssot__AiAgentSessionParticipant__dlm` DMO stores `ssot__ParticipantId__c` as either 15-char or 18-char Salesforce IDs, inconsistently. `AgentforceOptimizeService.resolvePlannerIds()` automatically handles both formats.
-
----
-
-## Data Space Name
-
-Always run Phase 0 first to discover the correct Data Space `name` for the org. Use `sf api request rest "/services/data/v63.0/ssot/data-spaces" -o <org>` (no `--json` flag -- unsupported on this beta command). Never assume `'default'` without checking -- it is only a fallback if the API call fails.
-
----
-
-## Agent Name Resolution Reference
-
-The only Salesforce metadata object that should be queried directly is `GenAiPlannerDefinition` -- used exclusively for agent name resolution in the Routing step.
-
-| Object | Purpose | When to query |
-|---|---|---|
-| `GenAiPlannerDefinition` | The agent definition | Routing step only -- to resolve `MasterLabel`, `DeveloperName`, and `Id` |
-| `DataKnowledgeSpace` | Knowledge base container | Phase 1.5b Step 5 only -- if knowledge gaps are detected |
-
-**Do NOT query these objects directly** -- use the `.agent` file instead:
-- `GenAiPluginDefinition` (subagents) -- read from `.agent` file `subagent:` blocks
-- `GenAiPluginInstructionDef` (instructions) -- read from `.agent` file `reasoning: instructions:` blocks
-- `GenAiFunction` (actions) -- read from `.agent` file `reasoning: actions:` blocks
-
-The `.agent` file is the single source of truth. All fixes should be applied to it and deployed via the Phase 3 deployment chain.

package/skills/orchestrating-datacloud/CREDITS.md

@@ -1,15 +0,0 @@
-# Credits & Acknowledgments
-
-This skill family distills publicly shared Data Cloud implementation knowledge into sf-skills house style. Attribution is intentionally explicit because contributor credit is a core sf-skills principle.
-
----
-
-This family intentionally:
-- keeps sf-skills naming consistency (`*-datacloud`)
-- keeps the external CLI plugin outside this repo
-- favors deterministic helper scripts and reusable JSON templates
-- rewrites examples into generic sf-skills-style guidance rather than copying workshop-specific payloads
-
-See [UPSTREAM.md](UPSTREAM.md) for the maintenance contract.
-
----

package/skills/orchestrating-datacloud/README.md

@@ -1,127 +0,0 @@
-# orchestrating-datacloud
-
-Salesforce Data Cloud skill family for sf-skills. This is the **cross-phase orchestrator** for community-driven Data Cloud workflows built around the external `sf data360` CLI runtime.
-
-## What this skill is for
-
-Use `orchestrating-datacloud` when the task spans multiple Data Cloud phases:
-- connection + ingestion + harmonization setup
-- troubleshooting a Data Cloud pipeline end to end
-- managing data spaces or data kits
-- deciding which specialized Data Cloud skill to use next
-
-## What this skill is *not*
-
-- It does **not** vendor or fork the external Data Cloud CLI plugin.
-- It does **not** use MCP.
-- It does **not** replace phase-specific skills once the problem is localized.
-- It does **not** cover STDM/session tracing/parquet analysis; use `observing-agentforce` for that.
-
-## Data Cloud skill family
-
-| Skill | Purpose |
-|---|---|
-| [orchestrating-datacloud](../orchestrating-datacloud/) | Orchestrator, data spaces, data kits, cross-phase workflows |
-| [connecting-datacloud](../connecting-datacloud/) | Connections, connectors, source discovery |
-| [preparing-datacloud](../preparing-datacloud/) | Data streams, DLOs, transforms, DocAI |
-| [harmonizing-datacloud](../harmonizing-datacloud/) | DMOs, mappings, identity resolution, data graphs |
-| [segmenting-datacloud](../segmenting-datacloud/) | Segments, calculated insights |
-| [activating-datacloud](../activating-datacloud/) | Activations, activation targets, data actions |
-| [retrieving-datacloud](../retrieving-datacloud/) | SQL, async query, vector search, search indexes |
-
-## Runtime model
-
-This family assumes:
-- Salesforce CLI (`sf`)
-- a Data Cloud-enabled org
-- the external community `sf data360` plugin linked into `sf`
-
-See [references/plugin-setup.md](references/plugin-setup.md).
-
-## Deterministic helpers included
-
-| Path | Purpose |
-|---|---|
-| [scripts/bootstrap-plugin.sh](scripts/bootstrap-plugin.sh) | Clone/update the community plugin, compile it, and link it into `sf` |
-| [scripts/verify-plugin.sh](scripts/verify-plugin.sh) | Check that the runtime is available before starting Data Cloud work |
-| [scripts/diagnose-org.mjs](scripts/diagnose-org.mjs) | Classify org readiness by phase before mutating Data Cloud assets |
-| [references/feature-readiness.md](references/feature-readiness.md) | Map high-signal errors and feature gates to concrete next steps |
-| [assets/definitions/](assets/definitions/) | Generic JSON templates for repeatable Data Cloud definition files |
-| [UPSTREAM.md](UPSTREAM.md) | Upstream mapping for future distillation and maintenance |
-
-## Generic templates
-
-The family includes reusable starting points for:
-- data streams
-- DMOs
-- mappings
-- identity resolution rulesets
-- segments
-- search indexes
-
-These are intentionally generic and should be adapted to the target org.
-
-## Quick start
-
-### 1. Verify the runtime
-
-```bash
-bash ./scripts/verify-plugin.sh
-# or with an org alias
-bash ./scripts/verify-plugin.sh myorg
-```
-
-The helper treats `sf data360 doctor` as advisory and falls back to additional read-only smoke checks when an org is only partially provisioned.
-
-### 2. Diagnose feature readiness before mutating
-
-```bash
-node ./scripts/diagnose-org.mjs -o myorg --json
-# optional retrieve-plane probe, only when you know the table is real
-node ./scripts/diagnose-org.mjs -o myorg --phase retrieve --describe-table MyDMO__dlm --json
-```
-
-Use the diagnose helper to distinguish between:
-- feature-gated modules
-- empty-but-enabled modules
-- query-plane issues
-- runtime/auth problems
-
-### 3. Bootstrap the plugin if needed
-
-```bash
-python3 ~/.claude/sf-skills-install.py --with-datacloud-runtime
-# or run the helper script directly
-bash ./scripts/bootstrap-plugin.sh
-```
-
-### 4. Start with read-only inspection
-
-```bash
-sf data360 man
-sf data360 doctor -o myorg 2>/dev/null
-sf data360 dmo list -o myorg 2>/dev/null
-sf data360 segment list -o myorg 2>/dev/null
-sf data360 activation platforms -o myorg 2>/dev/null
-```
-
-## Common examples
-
-```text
-"Set up a Customer 360 proof of concept in Data Cloud"
-"Troubleshoot why my unified profiles are not increasing"
-"I need to figure out whether this issue is in mappings, identity resolution, or segment SQL"
-"Show me how to inspect data spaces and data kits for this org"
-```
-
-## References
-
-- [SKILL.md](SKILL.md) - Orchestrator guidance
-- [references/plugin-setup.md](references/plugin-setup.md) - Plugin install and verification
-- [references/feature-readiness.md](references/feature-readiness.md) - Readiness classification and setup guidance
-- [UPSTREAM.md](UPSTREAM.md) - Upstream tracking and distillation policy
-- [CREDITS.md](CREDITS.md) - Contributor and source attribution
-
-## Primary contributor
-
-**Gnanasekaran Thoppae** — primary contributor for the orchestrating-datacloud family.

package/skills/orchestrating-datacloud/SKILL.md

@@ -1,235 +0,0 @@
----
-name: orchestrating-datacloud
-description: "Salesforce Data Cloud product orchestrator for connect→prepare→harmonize→segment→act workflows. Use this skill when the user needs a multi-step Data Cloud pipeline, cross-phase troubleshooting, or data space and data kit management. TRIGGER when: user needs a multi-step Data Cloud pipeline, asks to set up or troubleshoot Data Cloud across phases, manages data spaces or data kits, or wants a cross-phase sf data360 workflow. DO NOT TRIGGER when: work is isolated to a single phase (use the matching phase-specific skill), the task is STDM/session tracing/parquet telemetry (use observing-agentforce), standard CRM SOQL (use querying-soql), or Apex implementation (use generating-apex)."
-compatibility: "Requires an external community sf data360 CLI plugin and a Data Cloud-enabled org"
-metadata:
-  version: "1.0"
----
-
-# orchestrating-datacloud: Salesforce Data Cloud Orchestrator
-
-Use this skill when the user needs **product-level Data Cloud workflow guidance** rather than a single isolated command family: pipeline setup, cross-phase troubleshooting, data spaces, data kits, or deciding whether a task belongs in Connect, Prepare, Harmonize, Segment, Act, or Retrieve.
-
-This skill intentionally follows sf-skills house style while using the external `sf data360` command surface as the runtime. The plugin is **not vendored into this repo**.
-
----
-
-## When This Skill Owns the Task
-
-Use `orchestrating-datacloud` when the work involves:
-- multi-phase Data Cloud setup or remediation
-- data spaces (`sf data360 data-space *`)
-- data kits (`sf data360 data-kit *`)
-- health checks (`sf data360 doctor`)
-- CRM-to-unified-profile pipeline design
-- deciding how to move from ingestion → harmonization → segmentation → activation
-- cross-phase troubleshooting where the root cause is not yet clear
-
-Delegate to a phase-specific skill when the user is focused on one area:
-
-| Phase | Use this skill | Typical scope |
-|---|---|---|
-| Connect | [connecting-datacloud](../connecting-datacloud/SKILL.md) | connections, connectors, source discovery |
-| Prepare | [preparing-datacloud](../preparing-datacloud/SKILL.md) | data streams, DLOs, transforms, DocAI |
-| Harmonize | [harmonizing-datacloud](../harmonizing-datacloud/SKILL.md) | DMOs, mappings, identity resolution, data graphs |
-| Segment | [segmenting-datacloud](../segmenting-datacloud/SKILL.md) | segments, calculated insights |
-| Act | [activating-datacloud](../activating-datacloud/SKILL.md) | activations, activation targets, data actions |
-| Retrieve | [retrieving-datacloud](../retrieving-datacloud/SKILL.md) | SQL, search indexes, vector search, async query |
-
-Delegate outside the family when the user is:
-- extracting Session Tracing / STDM telemetry → [observing-agentforce](../observing-agentforce/SKILL.md)
-- writing CRM SOQL only → [querying-soql](../querying-soql/SKILL.md)
-- loading CRM source data → [handling-sf-data](../handling-sf-data/SKILL.md)
-- creating missing CRM schema → [generating-custom-object](../generating-custom-object/SKILL.md) or [generating-custom-field](../generating-custom-field/SKILL.md)
-- implementing downstream Apex or Flow logic → [generating-apex](../generating-apex/SKILL.md), [generating-flow](../generating-flow/SKILL.md)
-
----
-
-## Required Context to Gather First
-
-Ask for or infer:
-- target org alias
-- whether the plugin is already installed and linked
-- whether the user wants design guidance, read-only inspection, or live mutation
-- data sources involved: CRM objects, external databases, file ingestion, knowledge, etc.
-- desired outcome: unified profiles, segments, activations, vector search, analytics, or troubleshooting
-- whether the user is working in the default data space or a custom one
-- whether the org has already been classified with `scripts/diagnose-org.mjs`
-- which command family is failing today, if any
-
-If plugin availability or org readiness is uncertain, start with:
-- [references/plugin-setup.md](references/plugin-setup.md)
-- [references/feature-readiness.md](references/feature-readiness.md)
-- `scripts/verify-plugin.sh`
-- `scripts/diagnose-org.mjs`
-- `scripts/bootstrap-plugin.sh`
-
----
-
-## Core Operating Rules
-
-- Use the external `sf data360` plugin runtime; do **not** reimplement or vendor the command layer.
-- Prefer the smallest phase-specific skill once the task is localized.
-- Run readiness classification before mutation-heavy work. Prefer `scripts/diagnose-org.mjs` over guessing from one failing command.
-- For `sf data360` commands, suppress linked-plugin warning noise with `2>/dev/null` unless the stderr output is needed for debugging.
-- Distinguish **Data Cloud SQL** from CRM SOQL.
-- Do **not** treat `sf data360 doctor` as a full-product readiness check; the current upstream command only checks the search-index surface.
-- Do **not** treat `query describe` as a universal tenant probe; only use it with a known DMO/DLO table after broader readiness is confirmed.
-- Preserve Data Cloud-specific API-version workarounds when they matter.
-- Prefer generic, reusable JSON definition files over org-specific workshop payloads.
-
----
-
-## Recommended Workflow
-
-### 1. Verify the runtime and auth
-Confirm:
-- `sf` is installed
-- the community Data Cloud plugin is linked
-- the target org is authenticated
-
-Recommended checks:
-```bash
-sf data360 man
-sf org display -o <alias>
-bash ./scripts/verify-plugin.sh <alias>
-```
-
-Treat `sf data360 doctor` as a broad health signal, not the sole gate. On partially provisioned orgs it can fail even when read-only command families like connectors, DMOs, or segments still work.
-
-### 2. Classify readiness before changing anything
-Run the shared classifier first:
-```bash
-node ./scripts/diagnose-org.mjs -o <org> --json
-```
-
-Only use a query-plane probe after you know the table name is real:
-```bash
-node ./scripts/diagnose-org.mjs -o <org> --phase retrieve --describe-table MyDMO__dlm --json
-```
-
-Use the classifier to distinguish:
-- empty-but-enabled modules
-- feature-gated modules
-- query-plane issues
-- runtime/auth failures
-
-### 3. Discover existing state with read-only commands
-Use targeted inspection after classification:
-```bash
-sf data360 doctor -o <org> 2>/dev/null
-sf data360 data-space list -o <org> 2>/dev/null
-sf data360 data-stream list -o <org> 2>/dev/null
-sf data360 dmo list -o <org> 2>/dev/null
-sf data360 identity-resolution list -o <org> 2>/dev/null
-sf data360 segment list -o <org> 2>/dev/null
-sf data360 activation platforms -o <org> 2>/dev/null
-```
-
-### 4. Localize the phase
-Route the task:
-- source/connector issue → Connect
-- ingestion/DLO/stream issue → Prepare
-- mapping/IR/unified profile issue → Harmonize
-- audience or insight issue → Segment
-- downstream push issue → Act
-- SQL/search/index issue → Retrieve
-
-### 5. Choose deterministic artifacts when possible
-Prefer JSON definition files and repeatable scripts over one-off manual steps. Generic templates live in:
-- `assets/definitions/data-stream.template.json`
-- `assets/definitions/dmo.template.json`
-- `assets/definitions/mapping.template.json`
-- `assets/definitions/relationship.template.json`
-- `assets/definitions/identity-resolution.template.json`
-- `assets/definitions/data-graph.template.json`
-- `assets/definitions/calculated-insight.template.json`
-- `assets/definitions/segment.template.json`
-- `assets/definitions/activation-target.template.json`
-- `assets/definitions/activation.template.json`
-- `assets/definitions/data-action-target.template.json`
-- `assets/definitions/data-action.template.json`
-- `assets/definitions/search-index.template.json`
-
-### 6. Verify after each phase
-Typical verification:
-- stream/DLO exists
-- DMO/mapping exists
-- identity resolution run completed
-- unified records or segment counts look correct
-- activation/search index status is healthy
-
----
-
-## High-Signal Gotchas
-
-- `connection list` requires `--connector-type`.
-- `dmo list --all` is useful when you need the full catalog, but first-page `dmo list` is often enough for readiness checks and much faster.
-- Segment creation may need `--api-version 64.0`.
-- `segment members` returns opaque IDs; use SQL joins for human-readable details.
-- `sf data360 doctor` can fail on partially provisioned orgs even when some read-only commands still work; fall back to targeted smoke checks.
-- `query describe` errors such as `Couldn't find CDP tenant ID` or `DataModelEntity ... not found` are query-plane clues, not automatic proof that the whole product is disabled.
-- Many long-running jobs are asynchronous in practice even when the command returns quickly.
-- Some Data Cloud operations still require UI setup outside the CLI runtime.
-
----
-
-## Output Format
-
-When finishing, report in this order:
-1. **Task classification**
-2. **Runtime status**
-3. **Readiness classification**
-4. **Phase(s) involved**
-5. **Commands or artifacts used**
-6. **Verification result**
-7. **Next recommended step**
-
-Suggested shape:
-
-```text
-Data Cloud task: <setup / inspect / troubleshoot / migrate>
-Runtime: <plugin ready / missing / partially verified>
-Readiness: <ready / ready_empty / partial / feature_gated / blocked>
-Phases: <connect / prepare / harmonize / segment / act / retrieve>
-Artifacts: <json files, commands, scripts>
-Verification: <passed / partial / blocked>
-Next step: <next phase, setup guidance, or cross-skill handoff>
-```
-
----
-
-## Cross-Skill Integration
-
-| Need | Delegate to | Reason |
-|---|---|---|
-| load or clean CRM source data | [handling-sf-data](../handling-sf-data/SKILL.md) | seed or fix source records before ingestion |
-| create missing CRM schema | [generating-custom-object](../generating-custom-object/SKILL.md), [generating-custom-field](../generating-custom-field/SKILL.md) | Data Cloud expects existing objects/fields |
-| deploy permissions or bundles | [deploying-metadata](../deploying-metadata/SKILL.md) | environment preparation |
-| write Apex against Data Cloud outputs | [generating-apex](../generating-apex/SKILL.md) | code implementation |
-| Flow automation after segmentation/activation | [generating-flow](../generating-flow/SKILL.md) | declarative orchestration |
-| session tracing / STDM / parquet analysis | [observing-agentforce](../observing-agentforce/SKILL.md) | different Data Cloud use case |
-
----
-
-## Reference Map
-
-### Start here
-- [README.md](README.md)
-- [references/plugin-setup.md](references/plugin-setup.md)
-- [references/feature-readiness.md](references/feature-readiness.md)
-- [UPSTREAM.md](UPSTREAM.md)
-
-### Phase skills
-- [connecting-datacloud](../connecting-datacloud/SKILL.md)
-- [preparing-datacloud](../preparing-datacloud/SKILL.md)
-- [harmonizing-datacloud](../harmonizing-datacloud/SKILL.md)
-- [segmenting-datacloud](../segmenting-datacloud/SKILL.md)
-- [activating-datacloud](../activating-datacloud/SKILL.md)
-- [retrieving-datacloud](../retrieving-datacloud/SKILL.md)
-
-### Deterministic helpers
-- [scripts/bootstrap-plugin.sh](scripts/bootstrap-plugin.sh)
-- [scripts/verify-plugin.sh](scripts/verify-plugin.sh)
-- [scripts/diagnose-org.mjs](scripts/diagnose-org.mjs)
-- [assets/definitions/](assets/definitions/)

package/skills/orchestrating-datacloud/UPSTREAM.md

@@ -1,45 +0,0 @@
-# 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

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

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

@@ -1,7 +0,0 @@
-{
-  "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

@@ -1,7 +0,0 @@
-{
-  "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

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

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

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