@salesforce/afv-skills 1.21.0 → 1.23.0

package/skills/data360-orchestrate/UPSTREAM.md

@@ -0,0 +1,45 @@
+# Upstream Distillation Map for data360-orchestrate
+
+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:
+- `agentforce-observe` for STDM/session tracing/parquet workflows
+- `platform-soql-query` for CRM SOQL-only tasks
+- `platform-data-manage` for CRM record seeding/cleanup
+- `platform-*-generate` 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/data360-orchestrate/references/plugin-setup.md

@@ -0,0 +1,138 @@
+# Data Cloud Community Plugin Setup
+
+The data360-orchestrate 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
+
+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 ../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 ../scripts/generate-manifest.mjs .
+sf plugins link .
+```
+
+## Verification
+
+```bash
+sf data360 man
+bash ../scripts/verify-plugin.sh
+bash ../scripts/verify-plugin.sh myorg
+node ../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 ../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:
+- `data360-orchestrate`
+- `data360-connect`
+- `data360-prepare`
+- `data360-harmonize`
+- `data360-segment`
+- `data360-activate`
+- `data360-query`
+
+For STDM/session tracing/parquet work, use `agentforce-observe` instead of this plugin-focused family.

package/skills/data360-prepare/CREDITS.md

@@ -0,0 +1,7 @@
+# Credits & Acknowledgments
+
+Primary contributor: **Gnanasekaran Thoppae**
+
+This skill is part of the `*-datacloud` family. Shared attribution, upstream source mapping, and maintenance notes live in:
+- [../data360-orchestrate/CREDITS.md](../data360-orchestrate/CREDITS.md)
+- [../data360-orchestrate/UPSTREAM.md](../data360-orchestrate/UPSTREAM.md)

package/skills/data360-prepare/README.md

@@ -0,0 +1,51 @@
+# data360-prepare
+
+Ingestion and lake-preparation workflows for Salesforce Data Cloud.
+
+## Use this skill for
+
+- data streams
+- Data Lake Objects (DLOs)
+- data transforms
+- Document AI setup and extraction
+- unstructured ingestion and re-scan workflows
+- deciding how a source dataset should enter Data Cloud
+- classifying a dataset as `Profile`, `Engagement`, or `Other`
+- using the Ingestion API send-data example after connector setup
+
+## Example requests
+
+```text
+"Create a Data Cloud stream from Contact"
+"Inspect the DLO created by this stream"
+"Help me create a transform for ingested data"
+"Re-run this SharePoint document stream so it picks up new files"
+"Show me how to send records to Data Cloud through the Ingestion API"
+```
+
+## Common commands
+
+```bash
+sf data360 data-stream list -o myorg 2>/dev/null
+sf data360 data-stream create-from-object -o myorg --object Contact --connection SalesforceDotCom_Home 2>/dev/null
+sf data360 data-stream run -o myorg --name Contact_Home 2>/dev/null
+sf data360 dlo get -o myorg --name Contact_Home__dll 2>/dev/null
+sf data360 transform list -o myorg 2>/dev/null
+sf data360 connection run-existing -o myorg --name <connection-id> 2>/dev/null
+```
+
+## Key reminders
+
+- confirm whether a dataset should be treated as `Profile`, `Engagement`, or `Other` before creating the stream
+- `data-stream run` is the preferred re-scan path for unstructured document ingestion
+- `connection run-existing` is a connection-level rerun and is not a full substitute for stream refresh
+- some external database and Ingestion API stream-creation flows still require UI setup
+- initial unstructured DLO setup can be richer in the UI than in a minimal CLI payload
+- use the local [examples/ingestion-api/](examples/ingestion-api/) folder for the send-data flow
+
+## References
+
+- [SKILL.md](SKILL.md)
+- [examples/ingestion-api/README.md](examples/ingestion-api/README.md)
+- [../data360-orchestrate/assets/definitions/data-stream.template.json](../data360-orchestrate/assets/definitions/data-stream.template.json)
+- [CREDITS.md](CREDITS.md)

package/skills/data360-prepare/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: data360-prepare
+description: "Salesforce Data Cloud Prepare phase. Use this skill when the user creates or manages Data Cloud data streams, DLOs, transforms, or Document AI configurations. TRIGGER when: user creates or manages Data Cloud data streams, DLOs, transforms, or Document AI configurations, or asks about ingestion into Data Cloud. DO NOT TRIGGER when: the task is connection setup only (use data360-connect), DMOs and identity resolution (use data360-harmonize), or query/search work (use data360-query)."
+compatibility: "Requires an external community sf data360 CLI plugin and a Data Cloud-enabled org"
+metadata:
+  version: "1.0"
+---
+
+# data360-prepare: Data Cloud Prepare Phase
+
+Use this skill when the user needs **ingestion and lake preparation work**: data streams, Data Lake Objects (DLOs), transforms, Document AI, unstructured ingestion, or the handoff from connector setup into a live stream.
+
+## When This Skill Owns the Task
+
+Use `data360-prepare` when the work involves:
+- `sf data360 data-stream *`
+- `sf data360 dlo *`
+- `sf data360 transform *`
+- `sf data360 docai *`
+- choosing how data should enter Data Cloud
+- rerunning or rescanning ingestion after a source update
+- preparing Ingestion API-backed streams after connector setup is complete
+
+Delegate elsewhere when the user is:
+- still creating/testing source connections → [data360-connect](../data360-connect/SKILL.md)
+- mapping to DMOs or designing IR/data graphs → [data360-harmonize](../data360-harmonize/SKILL.md)
+- querying ingested data → [data360-query](../data360-query/SKILL.md)
+
+---
+
+## Required Context to Gather First
+
+Ask for or infer:
+- target org alias
+- source connection name
+- source object / dataset / document source
+- desired stream type
+- DLO naming expectations
+- whether the user is creating, updating, running, or deleting a stream
+- whether the source is CRM, a database connector, an unstructured file source, or an Ingestion API feed
+
+---
+
+## Core Operating Rules
+
+- Verify the external plugin runtime before running Data Cloud commands.
+- Run the shared readiness classifier before mutating ingestion assets: `node ../data360-orchestrate/scripts/diagnose-org.mjs -o <org> --phase prepare --json`.
+- Prefer inspecting existing streams and DLOs before creating new ingestion assets.
+- Suppress linked-plugin warning noise with `2>/dev/null` for normal usage.
+- Treat DLO naming and field naming as Data Cloud-specific, not CRM-native.
+- Confirm whether each dataset should be treated as `Profile`, `Engagement`, or `Other` before creating the stream.
+- Distinguish stream-level refresh from connection-level reruns when working with unstructured sources.
+- Use UI setup intentionally when initial stream or unstructured asset creation is platform-gated.
+- Hand off to Harmonize only after ingestion assets are clearly healthy.
+
+---
+
+## Recommended Workflow
+
+### 1. Classify readiness for prepare work
+```bash
+node ../data360-orchestrate/scripts/diagnose-org.mjs -o <org> --phase prepare --json
+```
+
+### 2. Inspect existing ingestion assets
+```bash
+sf data360 data-stream list -o <org> 2>/dev/null
+sf data360 dlo list -o <org> 2>/dev/null
+```
+
+### 3. Confirm the stream category before creation
+Use these rules when suggesting categories:
+
+| Category | Use for | Typical requirement |
+|---|---|---|
+| `Profile` | person/entity records | primary key |
+| `Engagement` | time-based events or interactions | primary key + event time field |
+| `Other` | reference/configuration/supporting datasets | primary key |
+
+When the source is ambiguous, ask the user explicitly whether the dataset should be treated as `Profile`, `Engagement`, or `Other`.
+
+### 4. Create or inspect streams intentionally
+```bash
+sf data360 data-stream get -o <org> --name <stream> 2>/dev/null
+sf data360 data-stream create-from-object -o <org> --object Contact --connection SalesforceDotCom_Home 2>/dev/null
+sf data360 data-stream create -o <org> -f stream.json 2>/dev/null
+sf data360 data-stream run -o <org> --name <stream> 2>/dev/null
+```
+
+### 5. Check DLO shape
+```bash
+sf data360 dlo get -o <org> --name Contact_Home__dll 2>/dev/null
+```
+
+### 6. Choose the right refresh mechanism
+Use the smaller refresh scope that matches the user goal:
+
+```bash
+sf data360 data-stream run -o <org> --name <stream> 2>/dev/null
+sf data360 connection run-existing -o <org> --name <connection-id> 2>/dev/null
+```
+
+- `data-stream run` is the closest match to a stream-level refresh or re-scan.
+- `connection run-existing` runs at the connection level and can be useful for some connector workflows, but it is not a reliable replacement for stream refresh on unstructured sources.
+- For unstructured document connectors, prefer `data-stream run` when the goal is to re-scan newly added or changed files.
+
+### 7. Handle unstructured sources deliberately
+For SharePoint-style document ingestion, a minimal unstructured DLO payload can look like:
+
+```json
+{
+  "name": "my_udlo",
+  "label": "My UDLO",
+  "category": "Directory_Table",
+  "dataSource": {
+    "sourceType": "SF_DRIVE",
+    "directoryAndFilesDetails": [
+      {
+        "dirName": "SPUnstructuredDocument/<CONNECTION_ID>/<SITE_ID>",
+        "fileName": "*"
+      }
+    ],
+    "sourceConfig": {
+      "reservedPrefix": "$dcf_content$"
+    }
+  }
+}
+```
+
+Use the UI for the first-time unstructured setup when the user needs the richer end-to-end pipeline. The UI path can seed additional document metadata fields and downstream assets that a bare CLI DLO create flow may not provision automatically.
+
+### 8. Use the local Ingestion API example for send-data workflows
+For external systems pushing records into Data Cloud:
+
+1. create the connector in [data360-connect](../data360-connect/SKILL.md)
+2. upload the schema with `sf data360 connection schema-upsert`
+3. create the stream in the UI when required
+4. send records with the local example in `examples/ingestion-api/`
+
+```bash
+cd examples/ingestion-api
+cp .env.example .env
+python3 send-data.py
+```
+
+Key details:
+- auth is a staged flow: JWT → Salesforce token → Data Cloud token
+- the ingestion endpoint uses the tenant URL, not the Salesforce instance URL
+- `202` means the payload was accepted for processing, not that records are queryable immediately
+- validation failures often surface in the Problem Records DLO family
+
+### 9. Only then move into harmonization
+Once the stream and DLO are healthy, hand off to [data360-harmonize](../data360-harmonize/SKILL.md).
+
+---
+
+## High-Signal Gotchas
+
+- CRM-backed stream behavior is not the same as fully custom connector-framework ingestion.
+- `sf data360 data-stream run` and `sf data360 connection run-existing` are not interchangeable; prefer stream-level refresh for unstructured rescans.
+- `SFDC` streams sync on a platform-managed schedule; `data-stream run` is not the general control path for CRM connector refresh.
+- Some external database connectors can be created via API while stream creation still requires UI flow or org-specific browser automation. Do not promise a pure CLI stream-creation path for every connector type.
+- Initial SharePoint-style unstructured setup can be richer in the UI than in a minimal CLI DLO create flow.
+- Stream deletion can also delete the associated DLO unless the delete mode says otherwise.
+- DLO field naming differs from CRM field naming, including `__c` → `_c` transformations.
+- Query DLO record counts with Data Cloud SQL instead of assuming list output is sufficient.
+- `CdpDataStreams` means the stream module is gated for the current org/user; guide the user to provisioning/permissions review instead of retrying blindly.
+
+---
+
+## Output Format
+
+```text
+Prepare task: <stream / dlo / transform / docai>
+Source: <connection + object>
+Target org: <alias>
+Artifacts: <stream names / dlo names / json definitions>
+Verification: <passed / partial / blocked>
+Next step: <harmonize or retrieve>
+```
+
+---
+
+## References
+
+- [README.md](README.md)
+- [examples/ingestion-api/README.md](examples/ingestion-api/README.md)
+- [../data360-orchestrate/assets/definitions/data-stream.template.json](../data360-orchestrate/assets/definitions/data-stream.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-prepare/examples/ingestion-api/README.md

@@ -0,0 +1,48 @@
+# Ingestion API example
+
+This folder contains a minimal, public-safe example for sending records into Salesforce Data Cloud through the Ingestion API.
+
+## What this example assumes
+
+Before running `send-data.py`, complete the connect/prepare setup steps:
+
+1. create an Ingestion API connector
+2. upload the schema with `sf data360 connection schema-upsert`
+3. create the corresponding data stream in the UI if your org requires that step
+
+Related connector definitions live in:
+- [../../../data360-connect/examples/connections/ingest-api-connection.json](../../../data360-connect/examples/connections/ingest-api-connection.json)
+- [../../../data360-connect/examples/connections/ingest-api-schema.json](../../../data360-connect/examples/connections/ingest-api-schema.json)
+
+## Prerequisites
+
+```bash
+pip install PyJWT cryptography requests
+```
+
+## Setup
+
+```bash
+cd skills/data360-prepare/examples/ingestion-api
+cp .env.example .env
+# edit .env with your values
+python3 send-data.py
+```
+
+## Environment variables
+
+- `CONSUMER_KEY` — external client app consumer key
+- `CONSUMER_SECRET` — external client app consumer secret if your auth flow needs it
+- `SF_USERNAME` — Salesforce username used for JWT auth
+- `SF_LOGIN_URL` — login host such as `https://login.salesforce.com`
+- `TENANT_URL` — Data Cloud tenant URL such as `https://<tenant>.c360a.salesforce.com`
+- `PRIVATE_KEY_FILE` — path to the JWT private key
+- `CONNECTOR_NAME` — Ingestion API connector name
+- `OBJECT_NAME` — uploaded schema object name
+
+## Notes
+
+- auth is a staged flow: JWT → Salesforce token → Data Cloud token
+- the ingestion endpoint uses the Data Cloud tenant URL, not the Salesforce instance URL
+- `202` means the payload was accepted for processing
+- validation failures often appear in the Problem Records DLO family

package/skills/data360-query/CREDITS.md

@@ -0,0 +1,7 @@
+# Credits & Acknowledgments
+
+Primary contributor: **Gnanasekaran Thoppae**
+
+This skill is part of the `*-datacloud` family. Shared attribution, upstream source mapping, and maintenance notes live in:
+- [../data360-orchestrate/CREDITS.md](../data360-orchestrate/CREDITS.md)
+- [../data360-orchestrate/UPSTREAM.md](../data360-orchestrate/UPSTREAM.md)

package/skills/data360-query/README.md

@@ -0,0 +1,44 @@
+# data360-query
+
+Query and search workflows for Salesforce Data Cloud.
+
+## Use this skill for
+
+- quick SQL counts
+- paginated SQL (`sqlv2`)
+- async query lifecycles
+- table describe
+- vector search
+- hybrid search with optional prefilter
+- search index inspection and lifecycle work
+
+## Example requests
+
+```text
+"Run a Data Cloud SQL query against unified profiles"
+"Describe this Data Cloud table before I write SQL"
+"Help me troubleshoot vector search in Data Cloud"
+"Run a hybrid search with a prefilter in Data Cloud"
+"Create and inspect a search index"
+```
+
+## Common commands
+
+```bash
+sf data360 query sql -o myorg --sql 'SELECT COUNT(*) FROM "ssot__Individual__dlm"' 2>/dev/null
+sf data360 query describe -o myorg --table ssot__Individual__dlm 2>/dev/null
+sf data360 search-index list -o myorg 2>/dev/null
+sf data360 query vector -o myorg --index Knowledge_Index --query "reset password" --limit 5 2>/dev/null
+sf data360 query hybrid -o myorg --index Knowledge_Index --query "reset password" --limit 5 2>/dev/null
+```
+
+## Example payloads
+
+- [examples/search-indexes/vector-knowledge.json](examples/search-indexes/vector-knowledge.json)
+- [examples/search-indexes/hybrid-structured.json](examples/search-indexes/hybrid-structured.json)
+
+## References
+
+- [SKILL.md](SKILL.md)
+- [../data360-orchestrate/assets/definitions/search-index.template.json](../data360-orchestrate/assets/definitions/search-index.template.json)
+- [CREDITS.md](CREDITS.md)

package/skills/data360-query/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: data360-query
+description: "Salesforce Data Cloud Retrieve phase. Use this skill when the user runs Data Cloud SQL, async queries, vector search, search-index workflows, or metadata introspection for Data Cloud objects. TRIGGER when: user runs Data Cloud SQL, describe, async queries, vector search, search-index workflows, or metadata introspection for Data Cloud objects. DO NOT TRIGGER when: the task is standard CRM SOQL (use platform-soql-query), segment creation or calculated insight design (use data360-segment), or STDM/session tracing/parquet analysis (use agentforce-observe)."
+compatibility: "Requires an external community sf data360 CLI plugin and a Data Cloud-enabled org"
+metadata:
+  version: "1.0"
+---
+
+# data360-query: Data Cloud Retrieve Phase
+
+Use this skill when the user needs **query, search, and metadata introspection** for Data Cloud: sync SQL, paginated SQL, async query workflows, table describe, vector search, hybrid search, or search index operations.
+
+## When This Skill Owns the Task
+
+Use `data360-query` when the work involves:
+- `sf data360 query *`
+- `sf data360 search-index *`
+- `sf data360 metadata *`
+- `sf data360 profile *` or `sf data360 insight *` inspection
+- understanding Data Cloud SQL results or query shape
+
+Delegate elsewhere when the user is:
+- writing standard CRM SOQL only → [platform-soql-query](../platform-soql-query/SKILL.md)
+- designing segment or calculated insight assets → [data360-segment](../data360-segment/SKILL.md)
+- analyzing STDM/session tracing/parquet telemetry → [agentforce-observe](../agentforce-observe/SKILL.md)
+
+---
+
+## Required Context to Gather First
+
+Ask for or infer:
+- target org alias
+- whether the user needs quick count, medium result set, large export, schema inspection, or semantic search
+- table/index name if known
+- whether the task is read-only SQL or search-index lifecycle management
+
+---
+
+## Core Operating Rules
+
+- Treat Data Cloud SQL as its own query language, not SOQL.
+- Run the shared readiness classifier before relying on query/search surfaces: `node ../data360-orchestrate/scripts/diagnose-org.mjs -o <org> --phase retrieve --json`.
+- Use describe before guessing columns.
+- Prefer `sqlv2` or async query flows for larger result sets.
+- Use vector search or hybrid search only when the search index lifecycle is healthy.
+- Keep STDM/parquet/session-tracing workflows out of this skill family.
+
+---
+
+## Recommended Workflow
+
+### 1. Classify readiness for retrieve work
+```bash
+node ../data360-orchestrate/scripts/diagnose-org.mjs -o <org> --phase retrieve --json
+# optional query-plane probe, only with a real table name
+node ../data360-orchestrate/scripts/diagnose-org.mjs -o <org> --phase retrieve --describe-table MyDMO__dlm --json
+```
+
+### 2. Choose the smallest correct query shape
+```bash
+sf data360 query sql -o <org> --sql 'SELECT COUNT(*) FROM "ssot__Individual__dlm"' 2>/dev/null
+sf data360 query sqlv2 -o <org> --sql 'SELECT * FROM "ssot__Individual__dlm"' 2>/dev/null
+sf data360 query async-create -o <org> --sql 'SELECT * FROM "ssot__Individual__dlm"' 2>/dev/null
+```
+
+### 3. Use describe before guessing fields
+```bash
+sf data360 query describe -o <org> --table ssot__Individual__dlm 2>/dev/null
+```
+
+### 4. Use vector or hybrid search only when an index exists
+```bash
+sf data360 search-index list -o <org> 2>/dev/null
+sf data360 query vector -o <org> --index Knowledge_Index --query "reset password" --limit 5 2>/dev/null
+sf data360 query hybrid -o <org> --index Knowledge_Index --query "reset password" --limit 5 2>/dev/null
+sf data360 query hybrid -o <org> --index Insurance_Index --query "weather damage coverage" --prefilter "Type_of_Insurance__c='Home'" --limit 10 2>/dev/null
+```
+
+### 5. Reuse curated search-index examples when creating indexes
+Use the phase-owned examples instead of inventing JSON from scratch:
+- `examples/search-indexes/vector-knowledge.json`
+- `examples/search-indexes/hybrid-structured.json`
+
+---
+
+## High-Signal Gotchas
+
+- Data Cloud SQL is not SOQL.
+- Table names should be double-quoted in SQL.
+- `sqlv2` is better than ad hoc OFFSET paging for medium result sets.
+- async query is preferable for large results.
+- search-index operations and vector/hybrid queries depend on the index lifecycle being healthy.
+- Hybrid search can use `--prefilter`, but only on fields configured as prefilter-capable when the search index was created.
+- HNSW index parameters are typically read-only on create; leave `userValues: []` unless the platform explicitly documents otherwise.
+- `query describe` is not a universal tenant probe; only run it with a known DMO or DLO table after broader readiness has been confirmed.
+
+---
+
+## Output Format
+
+```text
+Retrieve task: <sql / sqlv2 / async / describe / vector / search-index>
+Target org: <alias>
+Target object: <table or index>
+Commands: <key commands run>
+Verification: <query rows / schema / status>
+Next step: <segment / harmonize / follow-up>
+```
+
+---
+
+## References
+
+- [README.md](README.md)
+- [examples/search-indexes/vector-knowledge.json](examples/search-indexes/vector-knowledge.json)
+- [examples/search-indexes/hybrid-structured.json](examples/search-indexes/hybrid-structured.json)
+- [../data360-orchestrate/assets/definitions/search-index.template.json](../data360-orchestrate/assets/definitions/search-index.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-segment/CREDITS.md

@@ -0,0 +1,3 @@
+# Credits & Acknowledgments
+
+This skill is part of the `*-datacloud` family of skills covering the Salesforce Data Cloud workflow phases. Shared definitions, templates, and readiness scripts for this family live in the `data360-orchestrate` skill directory.