@salesforce/afv-skills 1.20.0 → 1.22.0

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-orchestrate/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"

package/skills/data360-orchestrate/scripts/diagnose-org.mjs

@@ -0,0 +1,511 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+
+const HELP = `Data Cloud org readiness classifier
+
+Usage:
+  node diagnose-org.mjs -o <orgAlias> [--json] [--phase <phase>] [--describe-table <table>] [--timeout <seconds>]
+
+Options:
+  -o, --target-org     Salesforce org alias or username (required)
+      --json           Print machine-readable JSON
+      --phase          Optional phase focus: all | connect | prepare | harmonize | segment | act | retrieve
+      --describe-table Optional DMO/DLO table name for a retrieve-plane probe
+      --timeout        Per-command timeout in seconds (default: 45)
+  -h, --help           Show this help text
+`;
+
+const FEATURE_GUIDANCE = {
+  CdpDataStreams: 'Data Streams are unavailable for this org/user. Review Data Cloud Setup provisioning, ingestion-related feature availability, and source connector permissions before using preparing-datacloud.',
+  CdpIdentityResolution: 'Identity Resolution is unavailable for this org/user. Review Data Cloud harmonization/identity-resolution entitlements and the user\'s Data Cloud permissions before using harmonizing-datacloud for IR work.',
+  CdpActivationTarget: 'Activation Targets are unavailable for this org/user. Review activation permissions, destination setup, and any org-specific activation enablement before using activating-datacloud.',
+  CdpActivationExternalPlatform: 'Activation destination platforms are unavailable for this org/user. Review Activation Targets setup, destination auth/configuration, and any feature toggles exposed in Data Cloud Setup → Feature Manager.',
+  CdpDataSpace: 'Data Spaces are unavailable for this org/user. Review core Data Cloud provisioning and user permissions in Data Cloud Setup before assuming downstream phases can work.',
+};
+
+const CAVEATS = [
+  'sf data360 doctor is advisory only: the current upstream command checks the search-index endpoint, not every Data Cloud module.',
+  'Do not use query describe as a universal tenant probe. Run it only after confirming broader readiness and only against a known DMO or DLO table.',
+  'Core Data Cloud provisioning, tenant creation, and license assignment are not reliably exposed as a full CLI enablement flow. Use CLI detection plus Setup guidance instead of promising fully programmatic enablement.',
+];
+
+function parseArgs(argv) {
+  const args = { phase: 'all', timeout: 45, json: false, describeTable: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    switch (arg) {
+      case '-o':
+      case '--target-org':
+        args.targetOrg = argv[++i];
+        break;
+      case '--phase':
+        args.phase = argv[++i] ?? 'all';
+        break;
+      case '--describe-table':
+        args.describeTable = argv[++i] ?? null;
+        break;
+      case '--timeout':
+        args.timeout = Number(argv[++i] ?? '45');
+        break;
+      case '--json':
+        args.json = true;
+        break;
+      case '-h':
+      case '--help':
+        args.help = true;
+        break;
+      default:
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  return args;
+}
+
+function trimText(text) {
+  return (text || '').replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, '').trim();
+}
+
+function runCommand(command, args, { json = false, timeoutSeconds = 45 } = {}) {
+  const finalArgs = [...args];
+  if (json && !finalArgs.includes('--json')) finalArgs.push('--json');
+  const result = spawnSync(command, finalArgs, {
+    encoding: 'utf8',
+    timeout: timeoutSeconds * 1000,
+  });
+
+  const stdout = result.stdout || '';
+  const stderr = result.stderr || '';
+  let parsed = null;
+  if (stdout.trim()) {
+    try {
+      parsed = JSON.parse(stdout);
+    } catch {
+      parsed = null;
+    }
+  }
+
+  let errorMessage = null;
+  if (result.error) {
+    if (result.error.code === 'ENOENT') {
+      errorMessage = `${command} is not installed or not on PATH.`;
+    } else if (result.error.code === 'ETIMEDOUT') {
+      errorMessage = `Timed out after ${timeoutSeconds}s`;
+    } else {
+      errorMessage = result.error.message;
+    }
+  }
+
+  return {
+    command: [command, ...finalArgs].join(' '),
+    exitCode: typeof result.status === 'number' ? result.status : 1,
+    stdout: trimText(stdout),
+    stderr: trimText(stderr),
+    parsed,
+    errorMessage,
+  };
+}
+
+function extractSuccessSample(parsed) {
+  const result = parsed?.result ?? {};
+
+  if (Array.isArray(result?.data)) {
+    return result.data[0] ?? null;
+  }
+  if (Array.isArray(result?.data?.platforms)) {
+    return result.data.platforms[0] ?? null;
+  }
+  if (Array.isArray(result?.semanticSearchDefinitionDetails)) {
+    return result.semanticSearchDefinitionDetails[0] ?? null;
+  }
+  return null;
+}
+
+function extractDetails(parsed) {
+  const result = parsed?.result ?? {};
+  if (result && typeof result === 'object' && !Array.isArray(result)) {
+    const details = { ...result };
+    delete details.data;
+    if (details.status || details.indexCount !== undefined || details.apiVersion || details.instanceUrl) {
+      return details;
+    }
+  }
+  return undefined;
+}
+
+function extractCount(parsed) {
+  const result = parsed?.result ?? {};
+  if (Array.isArray(result?.data)) return result.data.length;
+  if (typeof result?.totalSize === 'number') return result.totalSize;
+  if (Array.isArray(result?.data?.platforms)) return result.data.platforms.length;
+  if (typeof result?.indexCount === 'number') return result.indexCount;
+  return null;
+}
+
+function classifyError(message) {
+  const text = message || '';
+  const gateMatch = text.match(/\[([A-Za-z0-9]+)\]/);
+
+  if (text.includes("Couldn't find CDP tenant ID")) {
+    return {
+      state: 'query_service_unavailable',
+      code: 'QUERY_SERVICE_TENANT_LOOKUP_FAILED',
+      reason: 'The query service could not resolve a CDP tenant for this org context. Confirm broader readiness with data-space, DMO, or doctor probes before declaring Data Cloud fully disabled.',
+    };
+  }
+  if (text.includes('This feature is not currently enabled for this user type or org')) {
+    const featureCode = gateMatch?.[1] ?? 'UNKNOWN_FEATURE_GATE';
+    return {
+      state: 'feature_gated',
+      code: featureCode,
+      reason: FEATURE_GUIDANCE[featureCode] ?? 'This capability is gated for the current org or user. Review provisioning, permissions, and any relevant setup toggles before proceeding.',
+    };
+  }
+  if (text.includes('NOT_FOUND: DataModelEntity')) {
+    return {
+      state: 'table_not_found',
+      code: 'DATA_MODEL_ENTITY_NOT_FOUND',
+      reason: 'The specified DMO or DLO table name is not queryable in this org. Pick a real table from dmo list / dlo list or use dmo get first.',
+    };
+  }
+  if (text.includes('Request failed')) {
+    return {
+      state: 'request_failed',
+      code: 'REQUEST_FAILED',
+      reason: 'The endpoint returned a generic request failure. Treat this as inconclusive and confirm readiness with adjacent read-only probes.',
+    };
+  }
+  if (text.includes('is not a sf command') || text.includes('not installed or not on PATH')) {
+    return {
+      state: 'runtime_missing',
+      code: 'RUNTIME_MISSING',
+      reason: 'The sf data360 runtime is not available. Install or relink the community plugin first.',
+    };
+  }
+  if (text.includes('Timed out after')) {
+    return {
+      state: 'timeout',
+      code: 'TIMEOUT',
+      reason: 'The probe timed out. Retry, reduce the scope, or fall back to a smaller read-only command family.',
+    };
+  }
+  return {
+    state: 'unknown_error',
+    code: 'UNKNOWN_ERROR',
+    reason: 'The probe failed for an unclassified reason. Inspect the raw message and confirm readiness with neighboring probes.',
+  };
+}
+
+function normalizeProbe(name, raw, meta = {}) {
+  const base = {
+    name,
+    command: raw.command,
+    exitCode: raw.exitCode,
+    stderr: raw.stderr || undefined,
+    ...meta,
+  };
+
+  if (raw.errorMessage) {
+    const error = classifyError(raw.errorMessage);
+    return { ...base, ...error, message: raw.errorMessage };
+  }
+
+  if (raw.parsed && (raw.parsed.status === 0 || raw.exitCode === 0)) {
+    const count = extractCount(raw.parsed);
+    const sample = extractSuccessSample(raw.parsed);
+    const details = extractDetails(raw.parsed);
+    let state = 'ok';
+    if (count !== null) {
+      state = count > 0 ? 'enabled_populated' : 'enabled_empty';
+    }
+    if (raw.parsed?.result?.status === 'ok') {
+      state = 'ok';
+    }
+    return {
+      ...base,
+      state,
+      count,
+      sample: sample ?? undefined,
+      details,
+    };
+  }
+
+  const message = raw.parsed?.message || raw.stdout || raw.stderr || `Command failed with exit code ${raw.exitCode}`;
+  const error = classifyError(message);
+  return { ...base, ...error, message };
+}
+
+function summarizePhase(checks) {
+  const states = Object.values(checks).map((check) => check.state);
+  if (states.length === 0) return 'skipped';
+  if (states.every((state) => state === 'skipped')) return 'skipped';
+  const hasSuccess = states.some((state) => ['ok', 'enabled_empty', 'enabled_populated'].includes(state));
+  const hasPopulated = states.includes('enabled_populated');
+  const hasBlocking = states.some((state) => ['feature_gated', 'query_service_unavailable', 'request_failed', 'table_not_found', 'timeout', 'unknown_error'].includes(state));
+  if (hasSuccess && hasBlocking) return 'partial';
+  if (hasPopulated) return 'ready';
+  if (hasSuccess) return 'ready_empty';
+  if (states.every((state) => state === 'feature_gated')) return 'feature_gated';
+  if (states.every((state) => state === 'query_service_unavailable')) return 'query_unavailable';
+  if (states.every((state) => ['request_failed', 'timeout', 'unknown_error'].includes(state))) return 'blocked';
+  return 'unknown';
+}
+
+function guidanceFromProbe(scope, probe) {
+  if (!probe) return [];
+  if (['ok', 'enabled_empty', 'enabled_populated', 'skipped'].includes(probe.state)) return [];
+
+  if (probe.state === 'runtime_missing') {
+    return [
+      'Install or relink the community sf data360 runtime before attempting Data Cloud work.',
+      'Use python3 ~/.claude/sf-skills-install.py --with-datacloud-runtime or bash ./scripts/bootstrap-plugin.sh.',
+    ];
+  }
+
+  if (probe.state === 'query_service_unavailable') {
+    return [
+      `${scope}: query-specific tenant lookup failed. Do not treat this as a global Data Cloud outage by itself. Re-check core probes such as data-space list, dmo list, and doctor, then use a known table name if you retry query describe.`,
+    ];
+  }
+
+  if (probe.state === 'feature_gated') {
+    return [`${scope}: ${probe.reason}`];
+  }
+
+  if (probe.state === 'table_not_found') {
+    return [`${scope}: ${probe.reason}`];
+  }
+
+  if (probe.state === 'request_failed') {
+    return [
+      `${scope}: ${probe.reason}`,
+      'If doctor is the failing probe, remember that it only checks search indexes; use adjacent read-only probes before deciding the whole org is blocked.',
+    ];
+  }
+
+  if (probe.state === 'timeout') {
+    return [`${scope}: ${probe.reason}`];
+  }
+
+  return [`${scope}: ${probe.reason}`];
+}
+
+function parseOrgDisplay(raw, targetOrg) {
+  const base = {
+    alias: targetOrg,
+    state: 'ok',
+  };
+
+  if (raw.errorMessage) {
+    return { ...base, state: 'org_not_authenticated', message: raw.errorMessage };
+  }
+
+  if (raw.parsed && raw.parsed.status === 0) {
+    const result = raw.parsed.result || {};
+    return {
+      ...base,
+      alias: result.alias || targetOrg,
+      username: result.username,
+      instanceUrl: result.instanceUrl,
+      apiVersion: result.apiVersion,
+      connectedStatus: result.connectedStatus,
+    };
+  }
+
+  const message = raw.parsed?.message || raw.stdout || raw.stderr || `Failed to resolve org ${targetOrg}`;
+  return {
+    ...base,
+    state: 'org_not_authenticated',
+    message,
+  };
+}
+
+function buildProbeMatrix(orgAlias, describeTable) {
+  return {
+    core: {
+      doctor: ['data360', 'doctor', '-o', orgAlias],
+      dataSpaces: ['data360', 'data-space', 'list', '-o', orgAlias],
+      dmos: ['data360', 'dmo', 'list', '-o', orgAlias],
+    },
+    phases: {
+      connect: {
+        connectorCatalog: ['data360', 'connection', 'connector-list', '-o', orgAlias],
+        connectionsSalesforceCRM: ['data360', 'connection', 'list', '-o', orgAlias, '--connector-type', 'SalesforceCRM'],
+      },
+      prepare: {
+        dataStreams: ['data360', 'data-stream', 'list', '-o', orgAlias],
+        dlos: ['data360', 'dlo', 'list', '-o', orgAlias],
+      },
+      harmonize: {
+        dmos: ['data360', 'dmo', 'list', '-o', orgAlias],
+        identityResolution: ['data360', 'identity-resolution', 'list', '-o', orgAlias],
+      },
+      segment: {
+        segments: ['data360', 'segment', 'list', '-o', orgAlias],
+        calculatedInsights: ['data360', 'calculated-insight', 'list', '-o', orgAlias],
+      },
+      act: {
+        activationPlatforms: ['data360', 'activation', 'platforms', '-o', orgAlias],
+        activationTargets: ['data360', 'activation-target', 'list', '-o', orgAlias],
+        dataActionTargets: ['data360', 'data-action-target', 'list', '-o', orgAlias],
+      },
+      retrieve: {
+        searchIndexes: ['data360', 'search-index', 'list', '-o', orgAlias],
+        queryDescribe: describeTable
+          ? ['data360', 'query', 'describe', '-o', orgAlias, '--table', describeTable]
+          : null,
+      },
+    },
+  };
+}
+
+function printTextReport(report) {
+  const lines = [];
+  lines.push(`Data Cloud readiness for ${report.org.alias}`);
+  lines.push(`Runtime: ${report.runtime.state}`);
+  if (report.runtime.message) lines.push(`  ${report.runtime.message}`);
+  lines.push(`Org auth: ${report.org.state}`);
+  if (report.org.username) lines.push(`  User: ${report.org.username}`);
+  if (report.org.instanceUrl) lines.push(`  Instance: ${report.org.instanceUrl}`);
+  lines.push('');
+  lines.push('Core probes:');
+  for (const [name, probe] of Object.entries(report.core)) {
+    lines.push(`  - ${name}: ${probe.state}${probe.count !== null && probe.count !== undefined ? ` (${probe.count})` : ''}`);
+    if (probe.code) lines.push(`      code: ${probe.code}`);
+    if (probe.message) lines.push(`      ${probe.message}`);
+  }
+  lines.push('');
+  lines.push('Phase readiness:');
+  for (const [phase, entry] of Object.entries(report.phases)) {
+    lines.push(`  ${phase}: ${entry.summary}`);
+    for (const [name, probe] of Object.entries(entry.checks)) {
+      lines.push(`    - ${name}: ${probe.state}${probe.count !== null && probe.count !== undefined ? ` (${probe.count})` : ''}`);
+      if (probe.code) lines.push(`        code: ${probe.code}`);
+      if (probe.message) lines.push(`        ${probe.message}`);
+    }
+  }
+  lines.push('');
+  lines.push('Caveats:');
+  for (const caveat of report.caveats) {
+    lines.push(`  - ${caveat}`);
+  }
+  lines.push('');
+  lines.push('Guidance:');
+  if (report.guidance.length === 0) {
+    lines.push('  - No blocking issues detected from the chosen probes. Continue with read-only inspection, then mutate intentionally.');
+  } else {
+    for (const item of report.guidance) {
+      lines.push(`  - ${item}`);
+    }
+  }
+  console.log(lines.join('\n'));
+}
+
+function main() {
+  let args;
+  try {
+    args = parseArgs(process.argv.slice(2));
+  } catch (error) {
+    console.error(error.message);
+    console.error('');
+    console.error(HELP);
+    process.exit(1);
+  }
+
+  if (args.help) {
+    console.log(HELP);
+    process.exit(0);
+  }
+
+  if (!args.targetOrg) {
+    console.error('Missing required --target-org / -o argument.');
+    console.error('');
+    console.error(HELP);
+    process.exit(1);
+  }
+
+  const runtimeCheck = runCommand('sf', ['data360', 'man'], { json: false, timeoutSeconds: args.timeout });
+  const runtime = runtimeCheck.exitCode === 0
+    ? { state: 'ok', command: runtimeCheck.command }
+    : { ...classifyError(runtimeCheck.stderr || runtimeCheck.stdout || runtimeCheck.errorMessage || 'sf data360 runtime is unavailable'), command: runtimeCheck.command };
+
+  const orgDisplay = parseOrgDisplay(
+    runCommand('sf', ['org', 'display', '-o', args.targetOrg], { json: true, timeoutSeconds: args.timeout }),
+    args.targetOrg
+  );
+
+  const matrix = buildProbeMatrix(args.targetOrg, args.describeTable);
+  const report = {
+    runtime,
+    org: orgDisplay,
+    core: {},
+    phases: {},
+    caveats: [...CAVEATS],
+    guidance: [],
+  };
+
+  if (runtime.state !== 'ok' || orgDisplay.state !== 'ok') {
+    report.guidance.push(...guidanceFromProbe('runtime', runtime));
+    if (orgDisplay.state !== 'ok') {
+      report.guidance.push(`Authenticate the target org first: sf org login web -a ${args.targetOrg}`);
+    }
+    if (args.json) {
+      console.log(JSON.stringify(report, null, 2));
+    } else {
+      printTextReport(report);
+    }
+    process.exit(runtime.state === 'ok' && orgDisplay.state === 'ok' ? 0 : 1);
+  }
+
+  for (const [name, commandArgs] of Object.entries(matrix.core)) {
+    report.core[name] = normalizeProbe(name, runCommand('sf', commandArgs, { json: true, timeoutSeconds: args.timeout }));
+  }
+
+  const selectedPhases = args.phase === 'all'
+    ? Object.keys(matrix.phases)
+    : [args.phase];
+
+  for (const phase of selectedPhases) {
+    const checks = {};
+    const phaseMatrix = matrix.phases[phase] || {};
+    for (const [name, commandArgs] of Object.entries(phaseMatrix)) {
+      if (!commandArgs) {
+        checks[name] = { name, state: 'skipped', reason: 'No describe table was supplied for the query probe.' };
+        continue;
+      }
+      checks[name] = normalizeProbe(name, runCommand('sf', commandArgs, { json: true, timeoutSeconds: args.timeout }));
+    }
+    report.phases[phase] = {
+      summary: summarizePhase(checks),
+      checks,
+    };
+  }
+
+  const uniqueGuidance = new Set();
+  for (const [name, probe] of Object.entries(report.core)) {
+    for (const item of guidanceFromProbe(`core.${name}`, probe)) uniqueGuidance.add(item);
+  }
+  for (const [phase, entry] of Object.entries(report.phases)) {
+    for (const [name, probe] of Object.entries(entry.checks)) {
+      for (const item of guidanceFromProbe(`${phase}.${name}`, probe)) uniqueGuidance.add(item);
+    }
+  }
+
+  const coreSignals = Object.values(report.core).map((probe) => probe.state);
+  if (coreSignals.some((state) => ['ok', 'enabled_empty', 'enabled_populated'].includes(state))) {
+    uniqueGuidance.add('At least one core Data Cloud probe succeeded. Treat individual query or feature-gate failures as scoped issues, not automatic proof that the whole product is disabled.');
+  }
+  uniqueGuidance.add('For core provisioning, tenant creation, or license assignment gaps, use Setup → Data Cloud Setup and the current standard Data Cloud permission sets. Feature Manager can expose some org-specific toggles, but it is not the source of truth for every missing capability.');
+  uniqueGuidance.add('Reference: skills/orchestrating-datacloud/references/feature-readiness.md');
+
+  report.guidance = [...uniqueGuidance];
+
+  if (args.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    printTextReport(report);
+  }
+
+  process.exit(0);
+}
+
+main();