@salesforce/afv-skills 1.59.0 → 1.60.0

package/skills/consumer-goods-accruals-datakit-deploy/scripts/steps/utils.js

@@ -1,4 +1,4 @@
-const { execSync, execFileSync, spawnSync } = require('child_process');
+const { execSync, execFileSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
 
@@ -16,16 +16,7 @@ const ACCESS_TOKEN_VIA_SHOW_SINCE = [2, 136, 8];
 
 function getSfCliVersion() {
   try {
-    let raw;
-    if (process.platform === 'win32') {
-      const r = spawnSync('sf.cmd', ['version', '--json'], {
-        encoding: 'utf8', stdio: 'pipe', shell: true, windowsVerbatimArguments: true
-      });
-      if (r.error) return null;
-      raw = r.stdout;
-    } else {
-      raw = execFileSync(getSfBin(), ['version', '--json'], { encoding: 'utf8', stdio: 'pipe' });
-    }
+    const raw = execFileSync(getSfBin(), ['version', '--json'], { encoding: 'utf8', stdio: 'pipe' });
     const { cliVersion } = JSON.parse(raw);
     const m = (cliVersion || '').match(/(\d+)\.(\d+)\.(\d+)/);
     return m ? m.slice(1).map(Number) : null;
@@ -48,27 +39,10 @@ function isSfAtLeast(version, min) {
  * @param {string[]} args - CLI arguments
  * @returns {any} parsed JSON result
  */
-function execSfJson(args, options) {
-  options = options || {};
+function execSfJson(args) {
   let rawOutput;
   try {
-    if (process.platform === 'win32') {
-      // execFileSync cannot run .cmd files without shell:true, but shell:true
-      // word-splits args containing spaces. Use spawnSync with shell:true +
-      // windowsVerbatimArguments:true and pre-quote space-bearing args so that
-      // cmd.exe receives them intact.
-      const winArgs = args.map(a =>
-        (a.includes(' ') || a.includes("'")) ? `"${a.replace(/"/g, '\\"')}"` : a
-      );
-      const r = spawnSync('sf.cmd', winArgs, {
-        encoding: 'utf8', stdio: 'pipe', shell: true, windowsVerbatimArguments: true,
-        cwd: options.cwd
-      });
-      if (r.error) throw r.error;
-      rawOutput = r.stdout;
-    } else {
-      rawOutput = execFileSync(getSfBin(), args, { encoding: 'utf8', stdio: 'pipe', cwd: options.cwd });
-    }
+    rawOutput = execFileSync(getSfBin(), args, { encoding: 'utf8', stdio: 'pipe' });
   } catch (err) {
     if (err.stdout) {
       rawOutput = err.stdout;
@@ -227,12 +201,6 @@ function getBundleStreamMap(dataKitPath) {
     .filter(f => f.endsWith('.dataStreamTemplate-meta.xml'));
 
   const bundleRegex = /<dataSourceBundleDefinition>\s*([^<\s]+)\s*<\/dataSourceBundleDefinition>/i;
-  // <sourceObjectName> is the stable identifier that appears verbatim (or as a prefix
-  // for ingest streams with hex suffixes) in DataKitDeploymentLog.ComponentName.
-  // E.g. sourceObjectName "tpm_accrualrule_ingest" → log "tpm_accrualrule_ingest_3ADCEDC6".
-  // Fall back to <dataSourceObject> if absent, then to the filename stem.
-  const srcObjNameRegex = /<sourceObjectName>\s*([^<\s]+)\s*<\/sourceObjectName>/i;
-  const srcObjRegex = /<dataSourceObject>\s*([^<\s]+)\s*<\/dataSourceObject>/i;
 
   for (const file of files) {
     const fullPath = path.join(templatesDir, file);
@@ -247,20 +215,12 @@ function getBundleStreamMap(dataKitPath) {
     if (!match) continue;
 
     const bundleName = match[1];
-    const srcObjNameMatch = content.match(srcObjNameRegex);
-    const srcObjMatch = content.match(srcObjRegex);
-    const streamDevName = srcObjNameMatch
-      ? srcObjNameMatch[1]
-      : srcObjMatch
-        ? srcObjMatch[1]
-        : file.replace(/\.dataStreamTemplate-meta\.xml$/, '');
+    const streamDevName = file.replace(/\.dataStreamTemplate-meta\.xml$/, '');
 
     if (!map.has(bundleName)) {
       map.set(bundleName, []);
     }
-    if (!map.get(bundleName).includes(streamDevName)) {
-      map.get(bundleName).push(streamDevName);
-    }
+    map.get(bundleName).push(streamDevName);
   }
 
   return map;
@@ -307,7 +267,7 @@ function findMatchingRecords(deploymentLog, spec, namespace) {
 function getDeploymentLogForComponents(orgAlias, componentSpecs) {
   console.log(`Checking deployment status for ${componentSpecs.length} components...`);
 
-  const query = `SELECT ComponentName, DeploymentStatus, DeploymentError FROM DataKitDeploymentLog ORDER BY CreatedDate DESC LIMIT 500`;
+  const query = `SELECT ComponentName, DeploymentStatus, DeploymentError FROM DataKitDeploymentLog ORDER BY CreatedDate DESC`;
 
   try {
     const result = execSfJson(['data', 'query', '--query', query, '--target-org', orgAlias, '--json']);
@@ -384,7 +344,7 @@ async function waitForDeploymentCompletion(orgAlias, componentSpecs, deploymentS
   console.log(`\nWaiting for deployment to complete...`);
   console.log(`Tracking ${componentSpecs.length} components`);
 
-  const maxWaitTime = 90 * 60 * 1000; // 90 minutes — production orgs typically take 60-90 min
+  const maxWaitTime = 30 * 60 * 1000; // 30 minutes
   const pollInterval = 60_000; // 60 seconds
   const startTime = Date.now();
 
@@ -393,7 +353,7 @@ async function waitForDeploymentCompletion(orgAlias, componentSpecs, deploymentS
 
   while (Date.now() - startTime < maxWaitTime) {
     const whereClause = deploymentStartTime ? `WHERE CreatedDate > ${deploymentStartTime}` : '';
-    const query = `SELECT ComponentName, DeploymentStatus, DeploymentError FROM DataKitDeploymentLog ${whereClause} ORDER BY CreatedDate DESC LIMIT 500`;
+    const query = `SELECT ComponentName, DeploymentStatus, DeploymentError FROM DataKitDeploymentLog ${whereClause} ORDER BY CreatedDate DESC`;
 
     let deploymentLog = [];
     try {
@@ -448,7 +408,7 @@ async function waitForDeploymentCompletion(orgAlias, componentSpecs, deploymentS
   if (pending.length > 0) {
     console.error(`Pending: ${pending.join(', ')}`);
   }
-  throw new Error(`Deployment timed out after ${maxWaitTime / 1000 / 60} minutes — ${pending.length} component(s) still in progress`);
+  process.exit(1);
 }
 
 /**
@@ -460,19 +420,7 @@ function execDeployJson(deployArgs, options) {
   const allArgs = deployArgs.concat(['--json']);
   let rawOutput;
   try {
-    if (process.platform === 'win32') {
-      const winArgs = allArgs.map(a =>
-        (a.includes(' ') || a.includes("'")) ? `"${a.replace(/"/g, '\\"')}"` : a
-      );
-      const r = spawnSync('sf.cmd', winArgs, {
-        encoding: 'utf8', stdio: 'pipe', shell: true, windowsVerbatimArguments: true,
-        cwd: options.cwd
-      });
-      if (r.error) throw r.error;
-      rawOutput = r.stdout;
-    } else {
-      rawOutput = execFileSync(getSfBin(), allArgs, { encoding: 'utf8', stdio: 'pipe', cwd: options.cwd });
-    }
+    rawOutput = execFileSync(getSfBin(), allArgs, { encoding: 'utf8', stdio: 'pipe', cwd: options.cwd });
   } catch (err) {
     if (err.stdout) {
       rawOutput = err.stdout;

package/skills/consumer-goods-rtr-datacloud-export-configure/SKILL.md

@@ -3,7 +3,8 @@ name: consumer-goods-rtr-datacloud-export-configure
 description: "Configure a Trade Promotion Management (TPM) org's RTR (Real Time Reporting) export pipeline to push promotion measures into Data Cloud (Data 360) for Trade Promotion Effectiveness (TPE) dashboards. Use when a customer or admin wants to set up the RTR export for Data Cloud measures, configure the RTR report for TPE, or as a delegated step from consumer-goods-tpe-dashboard-configure."
 metadata:
   version: "1.0"
-  domains: ["Consumer Goods"]
+  domains:
+    - "Consumer Goods"
   relatedSkills:
     - "consumer-goods-tpe-dashboard-configure"
   cliTools:

package/skills/consumer-goods-tpe-dashboard-configure/SKILL.md

@@ -4,7 +4,8 @@ description: "End-to-end headless setup of Trade Promotion Effectiveness (TPE) d
 metadata:
   version: "1.0"
   minApiVersion: "67.0"
-  domains: ["Consumer Goods"]
+  domains:
+    - "Consumer Goods"
   relatedSkills:
     - "consumer-goods-rtr-datacloud-export-configure"
     - "consumer-goods-tpe-dashboard-custom-kpi-configure"

package/skills/consumer-goods-tpe-dashboard-custom-kpi-configure/SKILL.md

@@ -3,7 +3,8 @@ name: consumer-goods-tpe-dashboard-custom-kpi-configure
 description: "Customize the Trade Promotion Effectiveness (TPE) Analytics dashboards' generic KPI slots (Promotion Measure 1-3, Tactic Measure 1-2) with customer-chosen KPI measure codes and display names, without touching the shipped base model. Use when a customer/admin wants to \"customize TPE dashboards\", \"change the KPIs on the Promotion/Tactic Analysis dashboard\", or \"swap in our own measure codes on the TPE dashboard\"."
 metadata:
   version: "1.0"
-  domains: ["Consumer Goods"]
+  domains:
+    - "Consumer Goods"
   relatedSkills:
     - "consumer-goods-tpe-dashboard-configure"
   cliTools:

package/skills/consumer-goods-tpe-datakit-deploy/SKILL.md

@@ -4,7 +4,8 @@ description: "Deploy the TPM Accruals Data Kit components specifically required
 metadata:
   version: "1.0"
   minApiVersion: "67.0"
-  domains: ["Consumer Goods"]
+  domains:
+    - "Consumer Goods"
   relatedSkills:
     - "consumer-goods-tpe-dashboard-configure"
   cliTools:

package/skills/data360-schema-get/SKILL.md

@@ -2,6 +2,8 @@
 name: data360-schema-get
 description: "Retrieve Data Lake Object (DLO) and Data Model Object (DMO) schema information from Salesforce Data Cloud using REST APIs. Use this skill when you need to inspect DLO or DMO field definitions, data types, or metadata. Takes org alias and optional DLO/DMO name as parameters."
 metadata:
+  version: "1.0"
+  domains: ["Data 360"]
   cliTools:
     - tool: ["pip"]
       semver: ">=23.0.0"
@@ -9,8 +11,6 @@ metadata:
       semver: ">=3.10.0"
     - tool: ["sf"]
       semver: ">=2.0.0"
-  version: "1.0"
-  domains: ["Data 360"]
 ---
 
 # data360-schema-get Skill
@@ -54,7 +54,7 @@ Example output:
 ┌────┬───────┬──────────────────────────┬────────────────────┬───────────┐
 │    │ Alias │ Username                 │ Org Id             │ Status    │
 ├────┼───────┼──────────────────────────┼────────────────────┼───────────┤
-│ 🍁 │ myorg │ chandresh@afvidedemo.org │ 00DKZ00000b80NT2AY │ Connected │
+│    │ myorg │ chandresh@afvidedemo.org │ 00DKZ00000b80NT2AY │ Connected │
 └────┴───────┴──────────────────────────┴────────────────────┴───────────┘
 ```
 

package/skills/design-systems-slds-validate/references/report-format.md

@@ -131,7 +131,7 @@ Suggestions for improvement.
 <details>
 <summary>Full Linter Output</summary>
 
-```
+```json
 {linter-output}
 ```
 

package/skills/dx-org-manage/SKILL.md

@@ -6,6 +6,7 @@ metadata:
   domains: ["Developer Experience"]
   minApiVersion: "60.0"
   relatedSkills:
+    - "dx-org-snapshot-manage"
     - "dx-org-switch"
     - "platform-metadata-deploy"
   cliTools:

package/skills/dx-org-shape-manage/SKILL.md

@@ -6,6 +6,7 @@ metadata:
   domains: ["Developer Experience"]
   relatedSkills:
     - "dx-org-manage"
+    - "dx-org-snapshot-manage"
   cliTools:
     - tool: ["sf"]
       semver: ">=2.0.0"

package/skills/dx-org-snapshot-manage/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: dx-org-snapshot-manage
+description: "ALWAYS USE THIS SKILL to create, check the status of, list, or delete scratch org snapshots. A snapshot is a point-in-time copy of a scratch org's metadata AND data, referenced by name in the `snapshot` field of a scratch org definition file. Use when the user asks to create/take a snapshot, check a snapshot's status or creation progress, list/show/view existing snapshots (including filtering for snapshots expiring soon), or delete/remove a snapshot. Requires a Dev Hub with Scratch Org Snapshots enabled. DO NOT TRIGGER for creating org shapes (use dx-org-shape-manage) or for creating scratch orgs, including from an existing snapshot via `--snapshot` (use dx-org-manage)."
+metadata:
+  version: "1.0"
+  domains: ["Developer Experience"]
+  minApiVersion: "60.0"
+  relatedSkills:
+    - "dx-org-manage"
+    - "dx-org-shape-manage"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+    - tool: ["jq"]
+      semver: ">=1.6"
+  accessCheck:
+    - type: "orgPref"
+      value: "ScratchOrgSnapshotPref"
+---
+
+# dx-org-snapshot-manage
+
+Coordinates the full lifecycle of Salesforce scratch org snapshots — **create**, **get** (status), **list**, and **delete** — via `sf org create snapshot`, `sf org get snapshot`, `sf org list snapshot`, and `sf org delete snapshot`. A snapshot is a point-in-time copy of a scratch org (its metadata **and** data) that you reference by name in a scratch org definition file to spin up new orgs from saved state.
+
+---
+
+## Tool Restrictions
+
+**Use ONLY the Bash tool** to execute the `sf org ... snapshot` commands. Do NOT use MCP tools — ignore them completely.
+
+**Output artifacts for eval/testing:** ALWAYS write the command's complete JSON response to a file when an output directory is available. Do NOT ask the user what file to write — this skill defines the filenames. After executing each command: (1) if the user specified an output path, write there immediately; (2) otherwise run `[ -d force-app/main/adk-eval-output/ ] && echo 'force-app/main/adk-eval-output'` to detect the eval directory; (3) write the command's full, unmodified JSON response to `<output-dir>/<filename>` using these filenames: `create-snapshot-result.json`, `get-snapshot-result.json`, `list-snapshots-result.json`, or `delete-snapshot-result.json`. This is the generated output — write it without asking. (4) If no output directory can be found by either check, include the command's complete, unmodified JSON response verbatim (e.g. in a fenced code block) in your final reply instead of skipping the artifact.
+
+---
+
+## Relationship to Other Skills
+
+This skill owns the **full snapshot lifecycle** — create, get status, list, and delete. It does not create scratch orgs.
+
+- **Any snapshot operation** (create, status, list, delete, expiry check) → this skill.
+- **Create a scratch org, including from an existing snapshot** (`--snapshot <name>`) → `dx-org-manage`.
+- **Org shapes** (baseline config without data, `sf org create/list/delete shape`) → `dx-org-shape-manage`. Shapes and snapshots are different artifacts with different commands — see the comparison below.
+
+| | Snapshot (this skill) | Org Shape (`dx-org-shape-manage`) |
+|--|----------|-----------|
+| Captures | Full point-in-time copy: metadata **and** data | Baseline config only: features, limits, edition, Metadata API settings |
+| Commands | `sf org create/get/list/delete snapshot` | `sf org create/list/delete shape` |
+| Referenced via | `snapshot` (name) in the scratch def file | `sourceOrg` (org ID) in the scratch def file |
+| Prerequisite | **Dev Hub** has Scratch Org Snapshots enabled | **Source org** has Org Shape for Scratch Orgs enabled |
+| Operates against | A **Dev Hub** (`--target-dev-hub`) | The **source org** (`--target-org`) |
+
+---
+
+## Scope
+
+- **In scope**: Creating (`sf org create snapshot`), getting status (`sf org get snapshot`), listing (`sf org list snapshot`), and deleting (`sf org delete snapshot`) scratch org snapshots
+- **Out of scope**: Creating org shapes (`dx-org-shape-manage`), creating scratch orgs — including from a snapshot (`dx-org-manage`)
+
+---
+
+## Required Inputs
+
+Infer from the user's request:
+
+- **Operation**: create, get, list, or delete (see Workflow step 1)
+- **Dev Hub**: Username or alias of the Dev Hub that owns the snapshots. Passed via `--target-dev-hub` (`-v`); optional if the `target-dev-hub` config variable is set. **All four commands** operate against a Dev Hub, never `--target-org`.
+- **Source org** (create only): Scratch org ID (starts with `00D`), username, or alias to snapshot. Passed via `--source-org` (`-o`).
+- **Snapshot name** (create only): A unique name for the snapshot, **max 15 characters**. Passed via `--name` (`-n`).
+- **Snapshot name or ID** (get & delete only): Name, or ID (starts with `0Oo`), of the snapshot. Passed via `--snapshot` (`-s`).
+- **Description** (create, optional): Documents snapshot contents.
+- **Expiry threshold in days** (expiring-soon listing only): There is no CLI flag for this — it's a client-side filter on `ExpirationDate` (see Command Patterns).
+
+---
+
+## Workflow
+
+1. **Identify the operation** and match it to the command pattern below.
+2. **Resolve the Dev Hub** — if `--target-dev-hub` isn't provided, check the default with `sf config get target-dev-hub`. Never fabricate a placeholder Dev Hub name (e.g. `my-dev-hub`) — an unresolved hub is a hard stop; advise `sf org login web --set-default-dev-hub` instead.
+3. **For create, confirm the source org and snapshot name** — the source must be a scratch org; the name must be unique in the Dev Hub and ≤15 characters.
+4. **Execute via Bash tool** with the `--json` flag.
+5. **Report the result** (see Output Expectations and the example files).
+
+### Command Patterns
+
+| Operation | User intent | Execute via Bash tool |
+|-----------|-------------|------------------------|
+| **Create** | Create snapshot with name only | `sf org create snapshot --source-org <orgId\|alias> --name <SnapshotName> --json` |
+| **Create** | Create snapshot with description | `sf org create snapshot --source-org <orgId\|alias> --name <SnapshotName> --description "<desc>" --json` |
+| **Create** | Specify Dev Hub explicitly | `sf org create snapshot --source-org <orgId\|alias> --name <SnapshotName> --target-dev-hub <devHub> --json` |
+| **Get** | Check a snapshot's status/details | `sf org get snapshot --snapshot <name\|0Oo...> --json` |
+| **List** | List all snapshots in the Dev Hub | `sf org list snapshot --json` |
+| **List** | List snapshots expiring within N days | `sf org list snapshot --json` → filter on `ExpirationDate` with `jq` (see `references/cli_flags.md`) |
+| **Delete** | Delete a snapshot (with confirm prompt) | `sf org delete snapshot --snapshot <name\|0Oo...> --json` |
+| **Delete** | Delete without prompting (scripts/CI) | `sf org delete snapshot --snapshot <name\|0Oo...> --no-prompt --json` |
+| **Delete** | Delete multiple/all snapshots | **First** `sf org list snapshot --json`, confirm the target names with the user, **then** run `sf org delete snapshot --snapshot <name>` once per snapshot — there is no bulk-delete command |
+
+**Snapshot creation is asynchronous.** `create` returns a record whose `Status` is typically `InProgress` initially, with `ExpirationDate` still `null`. Poll with `sf org get snapshot` until `Status` is `Active` (verified live against a real Dev Hub — see `examples/create_success_output.json` vs `examples/get_output.json`) before using the snapshot to create scratch orgs.
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|-----------|-----------|
+| Always use `--json` flag | Provides structured output for reliable parsing and error handling |
+| All commands operate against a **Dev Hub** | `--target-dev-hub` (not `--target-org`) — optional only if the `target-dev-hub` config is set |
+| Dev Hub must have **Scratch Org Snapshots** enabled | Otherwise commands fail — contact Salesforce to enable it |
+| Source org (create) must be a **scratch org** | Snapshots only work with scratch orgs |
+| Snapshot names must be **unique** in the Dev Hub, **≤15 characters** | Longer names fail with `STRING_TOO_LONG` (verified live) |
+| Creation is **asynchronous** | `create` may return before the snapshot is `Active` — poll with `sf org get snapshot` |
+| **There is no update/rename/extend-expiration command.** | Verified — the CLI (and the underlying platform object) exposes only create/get/list/delete. To change a snapshot's name, description, or expiration, delete it and create a new one. |
+| **There is no bulk-delete command.** | Each `sf org delete snapshot` call removes exactly one snapshot |
+| **`sf org list snapshot` has no server-side filters** | Returns every visible snapshot; filter status/expiry client-side (e.g. with `jq`) |
+| `delete` prompts for confirmation by default | Use `--no-prompt` (`-p`) for non-interactive/CI use |
+| **Bulk/`--no-prompt` deletes require an explicit confirmation step** | Before deleting multiple or all snapshots — or any delete with `--no-prompt` — first run `sf org list snapshot --json`, echo the resolved target names back to the user, and get explicit confirmation. Deletion is irreversible. |
+| Permissions affect visibility/deletion | Users see/delete only their own snapshots unless a Dev Hub admin grants View All / Modify All |
+
+---
+
+## Troubleshooting
+
+| Issue | Resolution |
+|-------|------------|
+| `@salesforce/plugin-signups does not exist in the registry` | Snapshot commands live in the `signups` plugin, bundled with a normal `sf` install. This means the CLI environment is incomplete (slim/offline image) — do NOT attempt `sf plugins install` in an offline environment, it will fail and loop. Advise repairing the environment (`sf update`, or a fresh install) from a connected machine. |
+| `Scratch Org Snapshots isn't enabled for your Dev Hub.` | The Dev Hub lacks the snapshot feature — contact Salesforce to enable it |
+| `No snapshot found with the given name or id: <value>` (`SingleRecordQuery_NoRecords`) | Verified live on `get`/`delete` — the name/ID doesn't exist in this Dev Hub. Run `sf org list snapshot --json` to see available snapshots |
+| `STRING_TOO_LONG` — "Org Snapshot Name: data value too large... (max length=15)" | Verified live — the `--name` value exceeds 15 characters. Shorten it and retry |
+| Snapshot name already exists (`DuplicateValue`) | Names must be unique per Dev Hub — choose a different name |
+| `Status` is `InProgress` for a while | Creation is asynchronous — keep polling `sf org get snapshot` until `Status` becomes `Active` |
+| `Status` is `Error` (see the `Error` field) | Read the `Error` field, delete the failed snapshot, and recreate |
+| `NotADevHubError` | The targeted org isn't a Dev Hub — point `--target-dev-hub` at an actual Dev Hub |
+| No default Dev Hub org found | Provide `--target-dev-hub <alias>` or set a default with `sf config set target-dev-hub=<alias>` |
+
+---
+
+## Output Expectations
+
+All commands return JSON when `--json` is used. `get`/`list` return the raw `OrgSnapshot` sobject record(s) — verified live, these include the sobject `attributes` wrapper plus `Id`, `SnapshotName`, `Description`, `Status` (`New`, `InProgress`, `Active`, `Error`, `Expired`, or `Deleted`), `SourceOrg`, `CreatedDate`, `LastModifiedDate`, `ExpirationDate` (`null` until `Active`), and `Error`.
+
+- **Create** → a single snapshot record (`Status` is `InProgress` immediately after creation; `ExpirationDate` is `null`).
+- **Get** → a single snapshot record — use it to poll `Status`.
+- **List** → an array of snapshot records, ordered by `CreatedDate`. Empty array if none exist.
+- **Delete** → `{ "id": "0Oo...", "success": true, "errors": [] }`. No result if the user declines the confirmation prompt.
+
+See the example files below for exact response structures (captured live against a real Dev Hub, not assumed).
+
+---
+
+## Cross-Skill Integration
+
+| Need | Delegate to |
+|------|-------------|
+| Create a scratch org from a snapshot | `dx-org-manage` skill (set `snapshot` to the snapshot name in the definition file, or `--snapshot <name>`) |
+| Create/list/delete an org **shape** instead of a snapshot | `dx-org-shape-manage` skill |
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|-------------|
+| `references/cli_flags.md` | Detailed flag reference across create/get/list/delete, including the `jq` pipeline for filtering snapshots expiring soon |
+| `references/snapshot_usage.md` | Using a snapshot name in a scratch org definition file, once it's `Active` |
+
+## Example Files
+
+| File | Purpose |
+|------|---------|
+| `examples/create_success_output.json` | Successful snapshot creation (`Status: InProgress`) |
+| `examples/create_error_output.json` | `STRING_TOO_LONG` — name over 15 characters |
+| `examples/get_output.json` | Get response for an `Active` snapshot (`ExpirationDate` populated) |
+| `examples/list_output.json` | List response — array of snapshot records |
+| `examples/delete_output.json` | Successful delete response |

package/skills/dx-org-snapshot-manage/examples/create_error_output.json

@@ -0,0 +1,16 @@
+{
+  "status": 1,
+  "name": "STRING_TOO_LONG",
+  "message": "Org Snapshot Name: data value too large: ThisNameIsWayTooLongForSnapshot (max length=15)",
+  "exitCode": 1,
+  "context": "SnapshotCreate",
+  "code": "STRING_TOO_LONG",
+  "commandName": "SnapshotCreate",
+  "data": {
+    "message": "Org Snapshot Name: data value too large: ThisNameIsWayTooLongForSnapshot (max length=15)",
+    "errorCode": "STRING_TOO_LONG",
+    "fields": ["SnapshotName"]
+  },
+  "stack": "STRING_TOO_LONG: Org Snapshot Name: data value too large: ThisNameIsWayTooLongForSnapshot (max length=15)...",
+  "warnings": []
+}

package/skills/dx-org-snapshot-manage/examples/create_success_output.json

@@ -0,0 +1,19 @@
+{
+  "status": 0,
+  "result": {
+    "attributes": {
+      "type": "OrgSnapshot",
+      "url": "/services/data/v68.0/sobjects/OrgSnapshot/0Oo5g00000001ABCAA"
+    },
+    "Id": "0Oo5g00000001ABCAA",
+    "SnapshotName": "MySnapshot",
+    "Description": "Baseline with Package v1.2.0",
+    "Status": "InProgress",
+    "SourceOrg": "00D5g00000001XyEAI",
+    "CreatedDate": "2026-08-25T21:57:58.000+0000",
+    "LastModifiedDate": "2026-08-25T21:57:59.000+0000",
+    "ExpirationDate": null,
+    "Error": null
+  },
+  "warnings": []
+}

package/skills/dx-org-snapshot-manage/examples/delete_output.json

@@ -0,0 +1,9 @@
+{
+  "status": 0,
+  "result": {
+    "id": "0Oo5g00000002DEFAA",
+    "success": true,
+    "errors": []
+  },
+  "warnings": []
+}

package/skills/dx-org-snapshot-manage/examples/get_output.json

@@ -0,0 +1,19 @@
+{
+  "status": 0,
+  "result": {
+    "attributes": {
+      "type": "OrgSnapshot",
+      "url": "/services/data/v68.0/sobjects/OrgSnapshot/0Oo5g00000001ABCAA"
+    },
+    "Id": "0Oo5g00000001ABCAA",
+    "SnapshotName": "MySnapshot",
+    "Description": "Baseline with Package v1.2.0",
+    "Status": "Active",
+    "SourceOrg": "00D5g00000001XyEAI",
+    "CreatedDate": "2026-08-21T22:04:47.000+0000",
+    "LastModifiedDate": "2026-08-21T22:06:21.000+0000",
+    "ExpirationDate": "2026-11-19",
+    "Error": null
+  },
+  "warnings": []
+}

package/skills/dx-org-snapshot-manage/examples/list_output.json

@@ -0,0 +1,36 @@
+{
+  "status": 0,
+  "result": [
+    {
+      "attributes": {
+        "type": "OrgSnapshot",
+        "url": "/services/data/v68.0/sobjects/OrgSnapshot/0Oo5g00000001ABCAA"
+      },
+      "Id": "0Oo5g00000001ABCAA",
+      "SnapshotName": "BaseSnapshot",
+      "Description": "QA fixture",
+      "Status": "Active",
+      "SourceOrg": "00D5g00000001XyEAI",
+      "CreatedDate": "2026-08-21T22:04:47.000+0000",
+      "LastModifiedDate": "2026-08-21T22:06:21.000+0000",
+      "ExpirationDate": "2026-11-19",
+      "Error": null
+    },
+    {
+      "attributes": {
+        "type": "OrgSnapshot",
+        "url": "/services/data/v68.0/sobjects/OrgSnapshot/0Oo5g00000002DEFAA"
+      },
+      "Id": "0Oo5g00000002DEFAA",
+      "SnapshotName": "MySnapshot",
+      "Description": "Baseline with Package v1.2.0",
+      "Status": "InProgress",
+      "SourceOrg": "00D5g00000001XyEAI",
+      "CreatedDate": "2026-08-25T21:57:58.000+0000",
+      "LastModifiedDate": "2026-08-25T21:57:59.000+0000",
+      "ExpirationDate": null,
+      "Error": null
+    }
+  ],
+  "warnings": []
+}