@salesforce/afv-skills 1.7.5 → 1.9.0

package/skills/modeling-omnistudio-epc-catalog/references/epc-field-guide.md

@@ -0,0 +1,90 @@
+<!-- Parent: modeling-omnistudio-epc-catalog/SKILL.md -->
+
+# EPC Field Guide (Product2 + Bundles + Attributes)
+
+This quick guide captures the minimum field set for creating CME EPC products and offer bundles in DataPack-style metadata.
+
+## Root Template Files (`assets/`)
+
+The skill root `assets/` directory contains a full template set aligned to the Business Internet Essential (VPL) bundle:
+
+- `product2-offer-template.json`
+- `attribute-assignment-template.json`
+- `product-child-item-template.json`
+- `pricebook-entries-template.json`
+- `price-list-entries-template.json`
+- `object-field-attributes-template.json`
+- `orchestration-scenarios-template.json`
+- `decomposition-relationships-template.json`
+- `compiled-attribute-overrides-template.json`
+- `override-definitions-template.json`
+- `parent-keys-template.json`
+
+## Product2: Minimum Recommended EPC Fields
+
+| Field | Purpose | Example |
+|---|---|---|
+| `Name` | Human-readable catalog name | `Business Internet Essential (VPL)` |
+| `ProductCode` | Stable technical identifier | `VEPC_OFFERING_BUSINESS_INTERNET_ESSENTIAL` |
+| `%vlocity_namespace%__GlobalKey__c` | Cross-environment stable key | UUID-like value |
+| `%vlocity_namespace%__SpecificationType__c` | Product classification | `Offer` |
+| `%vlocity_namespace%__SpecificationSubType__c` | Product subtype | `Bundle` |
+| `%vlocity_namespace%__Status__c` | EPC status | `Active` |
+| `%vlocity_namespace%__IsOrderable__c` | Order eligibility | `true` |
+| `IsActive` | Product availability | `true` |
+| `%vlocity_namespace%__SellingStartDate__c` | Sales lifecycle start | `2021-07-31T04:00:00.000Z` |
+
+## Attribute Metadata Blocks
+
+### `%vlocity_namespace%__AttributeMetadata__c`
+
+Contains category/group metadata and product attribute records:
+
+- category `Code__c`, `Name`, `displaySequence`
+- per-attribute `code`, `label`, `inputType`, `required`, `values[]`
+
+### `%vlocity_namespace%__AttributeDefaultValues__c`
+
+Map from attribute code to default value:
+
+```json
+{
+  "VEPC_ATTR_DOWNLOAD_SPEED": "50 Mbps",
+  "VEPC_ATTR_CONTRACT_TERM": "Month-to-Month"
+}
+```
+
+## Product Bundle Modeling (`%vlocity_namespace%__ProductChildItem__c`)
+
+Offer bundles are composed through child item rows:
+
+- one root row: `IsRootProductChildItem = true`
+- child rows: parent and child references + sequence and quantity settings
+
+Key quantity fields:
+
+- `%vlocity_namespace%__MinQuantity__c`
+- `%vlocity_namespace%__MaxQuantity__c`
+- `%vlocity_namespace%__Quantity__c`
+- `%vlocity_namespace%__MinMaxDefaultQty__c` (e.g., `"0, 1, 1"`)
+
+## Common Field Pitfalls
+
+| Pitfall | Impact | Fix |
+|---|---|---|
+| `ProductCode` reused for multiple products | Cart and quote ambiguity | Enforce unique catalog code |
+| Default attribute value missing from values list | Runtime configuration errors | Keep defaults inside valid value set |
+| Missing root ProductChildItem | Broken offer traversal | Always add root row |
+| Direct org-specific IDs in DataPack | Deploy failures across orgs | Use lookup source keys and global keys |
+
+## Included Example Packs
+
+The skill ships with:
+
+- `assets/` (canonical EPC bundle template set)
+- `assets/examples/samsung-galaxy-s22-bundle/` (bundle offer example)
+- `assets/examples/business-internet-premium-fttc-simple-offer/` (simple offer example)
+- `assets/examples/business-internet-pro-vpl-simple-offer/` (simple offer example)
+- `assets/examples/static-ip-simple-offer/` (simple offer example)
+
+The example folders contain related DataPack-style files, including Product2 payloads, attribute assignments, product child items, and pricing artifacts.

package/skills/modeling-omnistudio-epc-catalog/references/naming-conventions.md

@@ -0,0 +1,80 @@
+<!-- Parent: modeling-omnistudio-epc-catalog/SKILL.md -->
+
+# CME EPC Naming Conventions
+
+Use deterministic naming across products, attributes, and offer bundles. Names should remain stable across environments and releases.
+
+## Product Name
+
+Format:
+
+```text
+<Business Domain> <Tier/Variant> (<Channel or Variant Tag>)
+```
+
+Examples:
+
+- `Business Internet Essential (VPL)`
+- `Business Internet Premium (FTTC)`
+
+## Product Code
+
+Format:
+
+```text
+<PREFIX>_<ENTITY>_<DOMAIN>_<VARIANT>
+```
+
+Examples:
+
+- `VEPC_OFFERING_BUSINESS_INTERNET_ESSENTIAL`
+- `VEPC_SPEC_BUSINESS_ROUTER_ADVANCED`
+
+Rules:
+
+- Uppercase with underscores only
+- No environment suffixes (`_DEV`, `_UAT`, `_PROD`)
+- Stable after go-live
+
+## Attribute Code
+
+Format:
+
+```text
+VEPC_ATTR_<DOMAIN>_<ATTRIBUTE_NAME>
+```
+
+Examples:
+
+- `VEPC_ATTR_DOWNLOAD_SPEED`
+- `VEPC_ATTR_CONTRACT_TERM`
+
+## Attribute Category Code
+
+Format:
+
+```text
+VEPC_ATTRIBUTE_CATEGORY_<DOMAIN_BLOCK>
+```
+
+Examples:
+
+- `VEPC_ATTRIBUTE_CATEGORY_INTERNET_DETAILS`
+- `VEPC_ATTRIBUTE_CATEGORY_CONTRACT_DETAILS`
+
+## Offer Bundle Composition
+
+When naming bundles and child items:
+
+- Bundle parent `ProductCode` should indicate offering intent (`VEPC_OFFERING_*`)
+- Child product codes should represent reusable specs (`VEPC_SPEC_*` recommended)
+- Sequence values (`SeqNumber`, `ChildLineNumber`) should be unique per parent and spaced for future inserts
+
+## Anti-Patterns
+
+| Bad pattern | Why to avoid |
+|---|---|
+| `Product1`, `Offer_New`, `CatalogItemA` | Non-descriptive and unstable |
+| Mixed abbreviations without glossary | Hard to maintain and search |
+| Date/version in `ProductCode` | Breaks long-term references |
+| Same `ProductCode` in multiple products | Downstream ambiguity |

package/skills/modeling-omnistudio-epc-catalog/references/scoring-model.md

@@ -0,0 +1,57 @@
+# EPC Bundle Scoring Model (120 Points)
+
+Use this rubric when scoring or reviewing an existing EPC offer bundle. Score each category and sum for a total out of 120.
+
+**Thresholds**: `>= 95` Deploy-ready | `70–94` Needs review | `< 70` Block and fix.
+
+---
+
+## 1) Catalog Identity and Naming (20 points)
+
+- Product name is clear, unique, and follows naming conventions
+- `ProductCode` follows the deterministic convention (no environment suffixes)
+- `SpecificationType`, `SpecificationSubType`, and `Family` values are coherent
+- Stable keying: `GlobalKey` is a UUID-style value; source key is consistent across files
+
+---
+
+## 2) EPC Product Structure (20 points)
+
+- All required `Product2` and EPC fields are present and populated
+- Lifecycle dates (`EffectiveDate`, `SellingStartDate`) are set and logically ordered
+- `IsActive` and `%vlocity_namespace%__IsOrderable__c` flags are coherent with lifecycle status
+- Record type and catalog classification are consistent
+
+---
+
+## 3) Attribute Modeling (25 points)
+
+- Attributes are logically grouped by category
+- Every attribute default exists within its `values[]` array
+- Required, read-only, and filterable semantics are correctly set
+- Display sequences are unique within each category and use spaced values (10, 20, 30…)
+
+---
+
+## 4) Offer Bundle Composition (25 points)
+
+- Root `%vlocity_namespace%__ProductChildItem__c` row is present with `IsRootProductChildItem=true`
+- All child product references are valid and their sequence/line numbers are unique
+- `MinQuantity`, `MaxQuantity`, and default `Quantity` constraints are set correctly per child
+- Optional vs required semantics are reflected accurately in min/max/default values
+
+---
+
+## 5) DataPack Integrity (15 points)
+
+- All namespace placeholders (`%vlocity_namespace%`) are consistent across every file in the bundle
+- Lookup object references use GlobalKey / source key (no hardcoded org-specific IDs)
+- No environment-specific brittle fields (no `_DEV`, `_UAT`, `_PROD` suffixes in ProductCode or keys)
+
+---
+
+## 6) Documentation and Handoff (15 points)
+
+- Clear explanation of the modeled intent is included in the handoff block
+- Testing checklist is present (see `scripts/cli-validation-commands.sh`)
+- Risks and assumptions are explicitly called out in the completion block

package/skills/modeling-omnistudio-epc-catalog/scripts/cli-validation-commands.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# CLI commands for querying and validating EPC artifacts in a Salesforce org.
+# Usage: replace <org> with your authenticated org alias.
+
+# Query candidate EPC products
+sf data query \
+  -q "SELECT Id,Name,ProductCode,Family,IsActive FROM Product2 ORDER BY LastModifiedDate DESC" \
+  -o <org>
+
+# Query Product Child Items for an offer
+sf data query \
+  -q "SELECT Id,Name,%vlocity_namespace%__ParentProductName__c,%vlocity_namespace%__ChildProductName__c,%vlocity_namespace%__MinMaxDefaultQty__c FROM %vlocity_namespace%__ProductChildItem__c WHERE %vlocity_namespace%__ParentProductName__c='<Offer Name>'" \
+  -o <org>
+
+# Retrieve Product2 metadata package members
+sf project retrieve start -m Product2:<DeveloperNameOrName> -o <org>
+
+# Validate deployment in dry-run mode
+sf project deploy start -x manifest/package.xml --dry-run -o <org>

package/skills/modeling-omnistudio-epc-catalog/scripts/sample-invocations.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Sample skill invocation commands for common EPC modeling tasks.
+# Replace `cursor-agent` with your local agent command wrapper if different.
+
+# Create a new EPC offer bundle with full companion metadata
+cursor-agent "Create a Product2 offer bundle named Business Internet Plus with ProductCode BIZ-INT-PLUS-01, 3 child products, and generate all companion DataPack JSON files from the assets templates."
+
+# Add configurable attributes to an existing EPC Product2 record
+cursor-agent "Update Product2 Business Internet Essential with attribute metadata/defaults/assignments for Bandwidth, ContractTerm, and StaticIPCount, including valid values and defaults."
+
+# Build ProductChildItem relationships for an offer
+cursor-agent "Create root and child %vlocity_namespace%__ProductChildItem__c records for offer Business Internet Essential VPL with min/max/default quantity rules."
+
+# Review an existing DataPack for EPC modeling quality
+cursor-agent "Review the Product2 bundle JSON files under examples/business-internet-plus-bundle/, score against the 120-point rubric, and return risks plus required fixes."
+
+# Convert a spec product into a bundle-ready offer payload
+cursor-agent "Transform Product2 Dedicated Fiber 1G from spec product to offer bundle (SpecificationType=Offer, SpecificationSubType=Bundle) and generate aligned PCI + pricing artifacts."

package/skills/observing-agentforce/SKILL.md

@@ -4,7 +4,7 @@ description: "Analyze production Agentforce agent behavior using session traces
 allowed-tools: Bash Read Write Edit Glob Grep
 license: Apache-2.0
 metadata:
-  version: "0.5.1"
+  version: "1.0"
   last_updated: "2026-04-08"
   argument-hint: "<org-alias> [--agent-file <path>] [--session-id <id>] [--days <n>]"
   compatibility: claude-code

package/skills/orchestrating-datacloud/CREDITS.md

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

@@ -0,0 +1,129 @@
+# 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
+
+> The script examples below assume the skill is installed under `~/.claude/skills/` via the full Claude Code installer. If you are working from a repo checkout, run the same scripts from that checkout path.
+
+### 1. Verify the runtime
+
+```bash
+bash ~/.claude/skills/orchestrating-datacloud/scripts/verify-plugin.sh
+# or with an org alias
+bash ~/.claude/skills/orchestrating-datacloud/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 ~/.claude/skills/orchestrating-datacloud/scripts/diagnose-org.mjs -o myorg --json
+# optional retrieve-plane probe, only when you know the table is real
+node ~/.claude/skills/orchestrating-datacloud/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 ~/.claude/skills/orchestrating-datacloud/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

@@ -0,0 +1,236 @@
+---
+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)."
+license: MIT
+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 ~/.claude/skills/orchestrating-datacloud/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 ~/.claude/skills/orchestrating-datacloud/scripts/diagnose-org.mjs -o <org> --json
+```
+
+Only use a query-plane probe after you know the table name is real:
+```bash
+node ~/.claude/skills/orchestrating-datacloud/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/)