@salesforce/afv-skills 1.54.0 → 1.56.0

package/skills/dx-org-analyze/tests/test_consistency.sh

@@ -0,0 +1,428 @@
+#!/usr/bin/env bash
+# Consistency tests for dx-org-analyze SKILL.md and scripts.
+# Verifies skill structure, script references, and report contract.
+#
+# Usage: bash tests/test_consistency.sh
+# Exit 0 on all-pass, 1 on any failure.
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_FILE="$SCRIPT_DIR/../SKILL.md"
+SCRIPTS_DIR="$SCRIPT_DIR/../scripts"
+
+if [[ ! -f "$SKILL_FILE" ]]; then
+  echo "FAIL: SKILL.md not found at $SKILL_FILE"
+  exit 1
+fi
+
+PASS=0
+FAIL=0
+
+pass() { echo "  PASS: $1"; PASS=$((PASS + 1)); }
+fail() { echo "  FAIL: $1"; FAIL=$((FAIL + 1)); }
+
+# ============================================================
+echo "=== Test 1: YAML frontmatter is well-formed ==="
+# ============================================================
+
+if head -1 "$SKILL_FILE" | grep -q "^---$"; then
+  CLOSE_LINE=$(awk 'NR>1 && /^---$/ {print NR; exit}' "$SKILL_FILE")
+  if [[ -n "$CLOSE_LINE" ]]; then
+    pass "YAML frontmatter opens and closes (line $CLOSE_LINE)"
+  else
+    fail "YAML frontmatter has no closing ---"
+  fi
+else
+  fail "SKILL.md does not start with ---"
+fi
+
+# ============================================================
+echo ""
+echo "=== Test 2: Required frontmatter fields ==="
+# ============================================================
+
+CLOSE_LINE=$(awk 'NR>1 && /^---$/ {print NR; exit}' "$SKILL_FILE")
+if [[ -n "$CLOSE_LINE" ]]; then
+  FRONTMATTER=$(sed -n "1,${CLOSE_LINE}p" "$SKILL_FILE")
+  for field in "name:" "description:" "metadata:"; do
+    if echo "$FRONTMATTER" | grep -q "$field"; then
+      pass "Frontmatter has '$field'"
+    else
+      fail "Frontmatter missing '$field'"
+    fi
+  done
+  SKILL_NAME=$(echo "$FRONTMATTER" | grep "^name:" | awk '{print $2}')
+  EXPECTED_NAME=$(basename "$(cd "$SCRIPT_DIR/.." && pwd)")
+  if [[ "$SKILL_NAME" == "$EXPECTED_NAME" ]]; then
+    pass "Skill name '$SKILL_NAME' matches directory name"
+  else
+    fail "Skill name '$SKILL_NAME' doesn't match directory name '$EXPECTED_NAME'"
+  fi
+  if echo "$FRONTMATTER" | grep -q "version:"; then
+    pass "Frontmatter has 'metadata.version'"
+  else
+    fail "Frontmatter missing 'metadata.version'"
+  fi
+fi
+
+# ============================================================
+echo ""
+echo "=== Test 3: SKILL.md references both scripts ==="
+# ============================================================
+
+if grep -qF "collect_org_data.py" "$SKILL_FILE"; then
+  pass "References collect_org_data.py"
+else
+  fail "Missing reference to collect_org_data.py"
+fi
+
+if grep -qF "compute_diff.py" "$SKILL_FILE"; then
+  pass "References compute_diff.py"
+else
+  fail "Missing reference to compute_diff.py"
+fi
+
+# ============================================================
+echo ""
+echo "=== Test 4: Scripts exist and are executable ==="
+# ============================================================
+
+for script in "collect_org_data.py" "compute_diff.py"; do
+  SPATH="$SCRIPTS_DIR/$script"
+  if [[ -f "$SPATH" ]]; then
+    pass "Script exists: $script"
+  else
+    fail "Script missing: $script"
+  fi
+  if [[ -x "$SPATH" ]]; then
+    pass "Script is executable: $script"
+  else
+    fail "Script not executable: $script"
+  fi
+  if head -1 "$SPATH" | grep -q "python3"; then
+    pass "Script has python3 shebang: $script"
+  else
+    fail "Script missing python3 shebang: $script"
+  fi
+done
+
+# ============================================================
+echo ""
+echo "=== Test 5: Scripts accept --help ==="
+# ============================================================
+
+for script in "collect_org_data.py" "compute_diff.py"; do
+  if python3 "$SCRIPTS_DIR/$script" --help >/dev/null 2>&1; then
+    pass "$script --help exits 0"
+  else
+    fail "$script --help failed"
+  fi
+done
+
+# ============================================================
+echo ""
+echo "=== Test 6: collect_org_data.py has required flags ==="
+# ============================================================
+
+HELP_COLLECT=$(python3 "$SCRIPTS_DIR/collect_org_data.py" --help 2>&1)
+for flag in "org-alias" "output" "skip-deep-data"; do
+  if echo "$HELP_COLLECT" | grep -qF -- "--$flag"; then
+    pass "collect_org_data.py supports --$flag"
+  else
+    fail "collect_org_data.py missing flag: --$flag"
+  fi
+done
+
+# ============================================================
+echo ""
+echo "=== Test 7: compute_diff.py has required flags ==="
+# ============================================================
+
+HELP_DIFF=$(python3 "$SCRIPTS_DIR/compute_diff.py" --help 2>&1)
+for flag in "org-a" "org-b" "output" "format" "org-a-label" "org-b-label"; do
+  if echo "$HELP_DIFF" | grep -qF -- "--$flag"; then
+    pass "compute_diff.py supports --$flag"
+  else
+    fail "compute_diff.py missing flag: --$flag"
+  fi
+done
+
+# ============================================================
+echo ""
+echo "=== Test 8: SF CLI authentication documented ==="
+# ============================================================
+
+if grep -qF "sf org list" "$SKILL_FILE"; then
+  pass "Documents 'sf org list' for listing authenticated orgs"
+else
+  fail "Missing: sf org list"
+fi
+
+if grep -qF "sf data query" "$SKILL_FILE"; then
+  pass "Documents 'sf data query' for validating connectivity"
+else
+  fail "Missing: sf data query"
+fi
+
+if grep -qF "sf org login web" "$SKILL_FILE"; then
+  pass "Documents 'sf org login web' for authentication"
+else
+  fail "Missing: sf org login web"
+fi
+
+# ============================================================
+echo ""
+echo "=== Test 9: Drift score constants in compute_diff.py ==="
+# ============================================================
+
+DIFF_SCRIPT="$SCRIPTS_DIR/compute_diff.py"
+for term in "WEIGHT_METADATA" "WEIGHT_PERMISSION" "WEIGHT_PROFILE" "DRIFT_LEVELS"; do
+  if grep -qF "$term" "$DIFF_SCRIPT"; then
+    pass "Drift constant '$term' in compute_diff.py"
+  else
+    fail "Missing drift constant: '$term'"
+  fi
+done
+
+if grep -qF "0.6" "$DIFF_SCRIPT" && grep -qF "0.3" "$DIFF_SCRIPT" && grep -qF "0.1" "$DIFF_SCRIPT"; then
+  pass "Weights are 0.6 / 0.3 / 0.1"
+else
+  fail "Drift weights don't match expected 0.6 / 0.3 / 0.1"
+fi
+
+for level in "LOW" "MODERATE" "HIGH" "CRITICAL"; do
+  if grep -qF "\"$level\"" "$DIFF_SCRIPT"; then
+    pass "Severity level '$level' defined"
+  else
+    fail "Missing severity level: '$level'"
+  fi
+done
+
+# ============================================================
+echo ""
+echo "=== Test 10: System permissions support ==="
+# ============================================================
+
+COLLECT_SCRIPT="$SCRIPTS_DIR/collect_org_data.py"
+
+if grep -qF "collect_system_permissions" "$COLLECT_SCRIPT"; then
+  pass "collect_org_data.py has collect_system_permissions function"
+else
+  fail "collect_org_data.py missing collect_system_permissions"
+fi
+
+if grep -qF "PermissionsXxx" "$COLLECT_SCRIPT" || grep -qF "Permissions" "$COLLECT_SCRIPT" && grep -qF "PermissionSet" "$COLLECT_SCRIPT"; then
+  pass "collect_org_data.py queries PermissionsXxx fields on PermissionSet"
+else
+  fail "Missing PermissionsXxx/PermissionSet query"
+fi
+
+if grep -qF "system_permissions" "$COLLECT_SCRIPT"; then
+  pass "collect_org_data.py outputs system_permissions in result"
+else
+  fail "Missing system_permissions in output"
+fi
+
+DIFF_SCRIPT="$SCRIPTS_DIR/compute_diff.py"
+
+if grep -qF "diff_system_permissions" "$DIFF_SCRIPT"; then
+  pass "compute_diff.py has diff_system_permissions function"
+else
+  fail "compute_diff.py missing diff_system_permissions"
+fi
+
+if grep -qF "System Permissions" "$DIFF_SCRIPT"; then
+  pass "compute_diff.py renders System Permissions section in report"
+else
+  fail "Missing System Permissions section in markdown report"
+fi
+
+# ============================================================
+echo ""
+echo "=== Test 11: collect_org_data.py uses SF CLI and public APIs ==="
+# ============================================================
+
+COLLECT_SCRIPT="$SCRIPTS_DIR/collect_org_data.py"
+
+if grep -qF "sf org list metadata-types" "$COLLECT_SCRIPT" || grep -qF "metadata-types" "$COLLECT_SCRIPT"; then
+  pass "Uses sf CLI metadata-types for type discovery"
+else
+  fail "Missing sf CLI metadata type discovery"
+fi
+
+if grep -qF "sf org list metadata" "$COLLECT_SCRIPT" || grep -qF "list metadata" "$COLLECT_SCRIPT"; then
+  pass "Uses sf CLI to list metadata components"
+else
+  fail "Missing sf CLI metadata listing"
+fi
+
+if grep -qF "OrganizationSettingsDetail" "$COLLECT_SCRIPT"; then
+  pass "Uses OrganizationSettingsDetail for org settings (public API)"
+else
+  fail "Missing OrganizationSettingsDetail — must use public API for settings"
+fi
+
+if grep -qF "/limits/" "$COLLECT_SCRIPT"; then
+  pass "Uses REST /limits/ endpoint for org limits"
+else
+  fail "Missing /limits/ endpoint — must use public API for org limits"
+fi
+
+if grep -q "exit(2)\|sys.exit(2)" "$COLLECT_SCRIPT"; then
+  pass "Exits 2 on session expiry"
+else
+  fail "Missing exit code 2 for session expiry"
+fi
+
+# Verify internal tools are NOT present
+if grep -qF "hoseMyOrgPlease" "$COLLECT_SCRIPT"; then
+  fail "Still references hoseMyOrgPlease (internal-only tool, must be removed)"
+else
+  pass "No references to hoseMyOrgPlease (internal tool removed)"
+fi
+
+# ============================================================
+echo ""
+echo "=== Test 12: Core rules in SKILL.md ==="
+# ============================================================
+
+RULES=("Read-only" "never deploy" "session expired")
+
+for rule in "${RULES[@]}"; do
+  if grep -qiF "$rule" "$SKILL_FILE"; then
+    pass "Core rule/concept present: '$rule'"
+  else
+    fail "Missing: '$rule'"
+  fi
+done
+
+# ============================================================
+echo ""
+echo "=== Test 13: No hardcoded metadata type tiers ==="
+# ============================================================
+
+HARDCODED_TIERS=$(grep -cE "^\*\*Tier [0-9]" "$SKILL_FILE" || true)
+if [[ "$HARDCODED_TIERS" -eq 0 ]]; then
+  pass "No hardcoded tier lists in SKILL.md"
+else
+  fail "Found $HARDCODED_TIERS hardcoded tier lists — use describeMetadata instead"
+fi
+
+# ============================================================
+echo ""
+echo "=== Test 14: No internal-only references in SKILL.md ==="
+# ============================================================
+
+if grep -qF "hoseMyOrgPlease" "$SKILL_FILE"; then
+  fail "SKILL.md still references hoseMyOrgPlease (internal-only)"
+else
+  pass "No hoseMyOrgPlease references in SKILL.md"
+fi
+
+if grep -qF "SOAP Partner API" "$SKILL_FILE" || grep -qF "SOAP Login" "$SKILL_FILE"; then
+  fail "SKILL.md still references SOAP login (removed for external use)"
+else
+  pass "No SOAP login references in SKILL.md"
+fi
+
+if grep -qF "Web Login" "$SKILL_FILE" && grep -qF "sid cookie" "$SKILL_FILE"; then
+  fail "SKILL.md still references web login with sid cookie (removed for external use)"
+else
+  pass "No web login/cookie references in SKILL.md"
+fi
+
+# ============================================================
+echo ""
+echo "=== Test 15: introspect_org.py exists and is executable ==="
+# ============================================================
+
+INTROSPECT_SCRIPT="$SCRIPTS_DIR/introspect_org.py"
+if [[ -f "$INTROSPECT_SCRIPT" ]]; then
+  pass "Script exists: introspect_org.py"
+else
+  fail "Script missing: introspect_org.py"
+fi
+if [[ -x "$INTROSPECT_SCRIPT" ]]; then
+  pass "Script is executable: introspect_org.py"
+else
+  fail "Script not executable: introspect_org.py"
+fi
+if head -1 "$INTROSPECT_SCRIPT" | grep -q "python3"; then
+  pass "Script has python3 shebang: introspect_org.py"
+else
+  fail "Script missing python3 shebang: introspect_org.py"
+fi
+
+# ============================================================
+echo ""
+echo "=== Test 16: introspect_org.py --help and flags ==="
+# ============================================================
+
+if python3 "$INTROSPECT_SCRIPT" --help >/dev/null 2>&1; then
+  pass "introspect_org.py --help exits 0"
+else
+  fail "introspect_org.py --help failed"
+fi
+
+HELP_INTROSPECT=$(python3 "$INTROSPECT_SCRIPT" --help 2>&1)
+for flag in "org" "output" "format" "label"; do
+  if echo "$HELP_INTROSPECT" | grep -qF -- "--$flag"; then
+    pass "introspect_org.py supports --$flag"
+  else
+    fail "introspect_org.py missing flag: --$flag"
+  fi
+done
+
+# ============================================================
+echo ""
+echo "=== Test 17: SKILL.md documents introspect workflow ==="
+# ============================================================
+
+if grep -qF "introspect_org.py" "$SKILL_FILE"; then
+  pass "SKILL.md references introspect_org.py"
+else
+  fail "SKILL.md missing reference to introspect_org.py"
+fi
+
+if grep -qiF "Introspect Workflow" "$SKILL_FILE"; then
+  pass "SKILL.md has Introspect Workflow section"
+else
+  fail "SKILL.md missing Introspect Workflow section"
+fi
+
+if grep -qiF "single-org" "$SKILL_FILE" || grep -qiF "single org" "$SKILL_FILE"; then
+  pass "SKILL.md mentions single-org mode"
+else
+  fail "SKILL.md missing single-org mode documentation"
+fi
+
+if grep -qiF "introspect" "$SKILL_FILE"; then
+  pass "SKILL.md mentions introspect in description"
+else
+  fail "SKILL.md description missing introspect trigger phrases"
+fi
+
+# ============================================================
+echo ""
+echo "=== Test 18: introspect_org.py report sections ==="
+# ============================================================
+
+for section in "Metadata Inventory" "Installed Packages" "Org Settings" "Org Limits" "Licenses" "System Permissions" "Deep Data"; do
+  if grep -qF "$section" "$INTROSPECT_SCRIPT"; then
+    pass "introspect_org.py renders '$section' section"
+  else
+    fail "introspect_org.py missing '$section' section"
+  fi
+done
+
+# ============================================================
+echo ""
+echo "================================================"
+echo "Results: $PASS passed, $FAIL failed"
+echo "================================================"
+
+if [[ $FAIL -gt 0 ]]; then
+  exit 1
+fi
+exit 0

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

@@ -1,8 +1,8 @@
 ---
 name: dx-org-manage
-description: "INVOKE this skill to execute Salesforce org operations: create scratch orgs, list/display/resume/delete scratch orgs, create org snapshots, open orgs in browser. This skill EXECUTES operations immediately - it does NOT generate scripts or code files. ALWAYS invoke this skill (do not execute SF CLI commands directly) when user requests to: create a scratch org (from edition, definition file (.json), snapshot, or org shape), list/display/resume/delete scratch orgs, create an org snapshot, or open a Salesforce org. Trigger phrases include: 'create a snapshot', 'take a snapshot', 'create scratch org', 'new scratch org', 'spin up an org', 'create 5 scratch orgs', 'create org from snapshot', 'scratch-def.json', 'project-scratch-def.json', 'list scratch orgs', 'display org', 'delete scratch org', 'resume scratch org', 'open my Salesforce org', 'open org in browser'. Do NOT use for switching default org (use dx-org-switch) or deploying metadata (use platform-metadata-deploy)."
+description: "Use to EXECUTE Salesforce org operations immediately via the sf CLI (this skill runs them, it does NOT generate scripts): create scratch orgs (from edition, definition file, snapshot, or org shape), list/display/resume/delete scratch orgs, open orgs in browser. Trigger: 'create scratch org', 'create org from snapshot', 'delete scratch org', 'open my org'. Do NOT use for switching the default org (use dx-org-switch), deploying metadata (use platform-metadata-deploy), or creating/checking/listing/deleting org snapshots (use dx-org-snapshot-manage)."
 metadata:
-  version: "1.2"
+  version: "1.3"
   domains: ["Developer Experience"]
   minApiVersion: "60.0"
   relatedSkills:
@@ -19,7 +19,7 @@ metadata:
 
 **Tool constraint:** Use the Bash tool for all `sf` CLI commands. Always include `--json` for structured output. Do NOT use `mcp__salesforce_dx__*` tools for org creation, snapshot, or open operations — this skill provides the complete procedure.
 
-**Output artifacts for eval/testing:** ALWAYS write the command's 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 the command: (1) if the user specified an output path (e.g. "write all generated files into folder X"), 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 JSON response to `<output-dir>/<filename>` using these filenames: `scratch-org-result.json` for org creation (for a batch of N orgs, `scratch-org-result-1.json` … `scratch-org-result-N.json`), `scratch-org-list-result.json` for list, `org-display-result.json` for display, `scratch-org-resume-result.json` for resume, `scratch-org-delete-result.json` for delete, or `snapshot-result.json` for snapshot creation. This is the generated output — write it without asking. (Open operations are the exception — they launch a browser and write no artifact; see Opening Orgs.)
+**Output artifacts for eval/testing:** ALWAYS write the command's 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 the command: (1) if the user specified an output path (e.g. "write all generated files into folder X"), 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 JSON response to `<output-dir>/<filename>` using these filenames: `scratch-org-result.json` for org creation (for a batch of N orgs, `scratch-org-result-1.json` … `scratch-org-result-N.json`), `scratch-org-list-result.json` for list, `org-display-result.json` for display, `scratch-org-resume-result.json` for resume, or `scratch-org-delete-result.json` for delete. This is the generated output — write it without asking. (Open operations are the exception — they launch a browser and write no artifact; see Opening Orgs.)
 
 ---
 
@@ -118,7 +118,7 @@ Write the extracted org-list entry (the resolved org record), NOT the raw creati
 - For the complete creation workflow (AUTO MODE, STATE A/B, batch, definition-file authoring) → load `references/scratch-org-create.md`; for list/display/resume/delete → load `references/scratch-org-operations.md`
 - For available features, settings, and definition file structure → load `references/definition_file_options.md`
 - For edition selection guidance and comparison → load `references/edition_types.md`
-- For snapshot workflow and post-creation usage → load `references/snapshot_usage.md`
+- To create/check/list/delete the snapshot itself before referencing it here → use the `dx-org-snapshot-manage` skill
 
 ---
 
@@ -182,47 +182,6 @@ sf org delete scratch --target-org <alias> --no-prompt --json
 
 ---
 
-## Creating Snapshots
-
-**REQUIRED steps — execute in order:**
-
-**Step 1. Get inputs:**
-- Source org: scratch org ID or alias (from user)
-- Snapshot name: unique name (from user)
-- Description: optional (from user)
-
-**Step 2. Determine Dev Hub:** resolve to a concrete value and pass it explicitly via `--target-dev-hub` in Step 3 (same order as scratch-org creation — never guess a name):
-1. A Dev Hub the user named → use it verbatim.
-2. Else the default: non-empty `result[0].value` from `sf config get target-dev-hub --json`.
-3. Else the single authenticated Dev Hub — run **this exact all-bucket command** (do NOT hand-write a single-bucket filter, which misses hubs that land in `devHubs`/`nonScratchOrgs`):
-   ```bash
-   sf org list --json | jq -r '[.result.devHubs[]?, .result.nonScratchOrgs[]?, .result.other[]?, .result.sandboxes[]?, .result.scratchOrgs[]?] | map(select(.isDevHub == true).username) | unique | .[]'
-   ```
-   Exactly one → use it. Zero → **do NOT run the snapshot command at all**; advise `sf org login web --set-default-dev-hub` and stop. Two or more → ask the user which.
-
-Never fabricate a placeholder alias (e.g. `eval-target`, `my-dev-hub`) and never run the command with no `--target-dev-hub` flag — the CLI rejects a bad name with `NotADevHubError` and a missing default with `NoDefaultDevHubError`. If no hub resolves, that is a hard stop, not a value to guess.
-
-**Step 3. Execute:**
-```bash
-sf org create snapshot --source-org <orgId-or-alias> --name <SnapshotName> --target-dev-hub <devHub> --json
-```
-
-With description:
-```bash
-sf org create snapshot --source-org <orgId-or-alias> --name <SnapshotName> --description "<desc>" --target-dev-hub <devHub> --json
-```
-
-**Step 4. Report result:** Returns JSON with SnapshotId and Status. If an output directory is available (per the output artifacts rule above), write the JSON response to `<output-dir>/snapshot-result.json`.
-
-**Error handling:** surface the CLI's own error unchanged. For example:
-- "Snapshot name already exists" → use a different unique name
-
-**When you need more detail:**
-- For complete snapshot creation workflow and flag reference → load `references/creating-snapshot.md`
-- For CLI flag reference → load `references/cli_flags.md`
-
----
-
 ## Opening Orgs
 
 **REQUIRED steps — execute in order:**
@@ -264,11 +223,10 @@ Load these reference files for detailed guidance:
 | `references/scratch-org-operations.md` | Operating on existing orgs: list, display, resume, delete — plus shared lifecycle rules and troubleshooting |
 | `references/definition_file_options.md` | User needs to configure org features, settings, or advanced definition file options beyond basic org creation |
 | `references/edition_types.md` | User asks which edition to choose or needs to understand edition differences |
-| `references/snapshot_usage.md` | User wants to use snapshots in definition files or needs post-snapshot workflow guidance |
-| `references/cli_flags.md` | User needs complete snapshot CLI flag reference |
-| `references/creating-snapshot.md` | Troubleshooting snapshot creation failures or need detailed snapshot workflow |
 | `references/opening-org.md` | User needs to navigate to specific setup paths, open metadata files, or use advanced open flags |
 
+To create/check/list/delete a snapshot itself (rather than just consuming one), use the `dx-org-snapshot-manage` skill.
+
 ## Example Files
 
 Example command outputs for testing and troubleshooting:
@@ -285,5 +243,3 @@ Example command outputs for testing and troubleshooting:
 | `examples/scratch-orgs/display_output.json` | `sf org display --json` output (wrapped, tokens redacted) |
 | `examples/scratch-orgs/resume_output.json` | `sf org resume scratch --json` output (completed org) |
 | `examples/scratch-orgs/delete_output.json` | `sf org delete scratch --json` output |
-| `examples/snapshots/success_output.json` | Successful snapshot creation |
-| `examples/snapshots/error_output.json` | Common snapshot error scenario (duplicate name) |

package/skills/dx-org-manage/examples/README.md

@@ -1,20 +1,21 @@
 # Examples Directory
 
-This directory contains example outputs for the three workflows supported by the `dx-org-manage` skill.
+This directory contains example outputs for the workflows supported by the `dx-org-manage` skill.
+
+Snapshot lifecycle examples (create/get/list/delete the snapshot itself) live in the `dx-org-snapshot-manage` skill's `examples/` directory — this skill only *consumes* an existing snapshot (see `success_snapshot.json` below).
 
 ## Structure
 
 ```text
 examples/
 ├── README.md                          # This file
-├── scratch-orgs/                      # Scratch org creation examples
-│   ├── success_definition_file.json
-│   ├── success_edition.json
-│   ├── error_no_devhub.json
-│   └── error_timeout.json
-└── snapshots/                         # Snapshot creation examples
-    ├── success_output.json
-    └── error_output.json
+└── scratch-orgs/                      # Scratch org creation examples
+    ├── success_definition_file.json
+    ├── success_edition.json
+    ├── success_snapshot.json
+    ├── success_shape.json
+    ├── error_no_devhub.json
+    └── error_timeout.json
 ```
 
 ## scratch-orgs/
@@ -27,13 +28,6 @@ Examples of `sf org create scratch` command outputs for all four creation method
 - **error_no_devhub.json** - Error when Dev Hub not authenticated
 - **error_timeout.json** - Timeout error (exit code 69)
 
-## snapshots/
-
-Examples of `sf org create snapshot` command outputs.
-
-- **success_output.json** - Successful snapshot creation
-- **error_output.json** - Common error scenario (duplicate snapshot name)
-
 ## Usage
 
 These examples help illustrate:

package/skills/dx-org-manage/references/scratch-org-create.md

@@ -300,4 +300,4 @@ user-supplied name — the CLI auto-populates the org name.
 - `scratch-org-operations.md` — list, display, resume, delete
 - `definition_file_options.md` — features, settings, and definition-file schema
 - `edition_types.md` — edition selection and the CLI-flag-vs-definition-file format distinction
-- `snapshot_usage.md` — using snapshots in definition files and post-snapshot workflow
+- `dx-org-snapshot-manage` skill — create/check/list/delete a snapshot before referencing it here; this file only covers consuming an existing, `Active` snapshot via `--snapshot`/the `snapshot` definition-file field

package/skills/dx-org-manage/references/scratch-org-operations.md

@@ -132,4 +132,4 @@ sf org delete scratch --target-org <alias> --no-prompt --json
   AUTO MODE, STATE A/B, batch create, and definition-file authoring
 - `definition_file_options.md` — features, settings, and definition-file schema
 - `edition_types.md` — edition selection and the CLI-flag-vs-definition-file format distinction
-- `snapshot_usage.md` — using snapshots in definition files and post-snapshot workflow
+- `dx-org-snapshot-manage` skill — create/check/list/delete a snapshot before referencing it here; this file only covers consuming an existing, `Active` snapshot via `--snapshot`/the `snapshot` definition-file field

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

@@ -1,6 +1,6 @@
 ---
 name: dx-org-shape-manage
-description: "ALWAYS USE THIS SKILL to create, list, or delete org shapes. An org shape is a captured baseline configuration (features, limits, edition, and Metadata API settings) of a source org, without its data or metadata. Use when the user asks to create/make/take an org shape, capture or replicate an org's configuration/edition/limits, list/show/view existing org shapes (including INACTIVE/superseded ones) or their IDs and status, or delete/remove org shapes for a source org. Requires a source org with Dev Hub and Org Shape for Scratch Orgs enabled. DO NOT TRIGGER for creating snapshots or scratch orgs (use dx-org-manage)."
+description: "ALWAYS USE THIS SKILL to create, list, or delete org shapes. An org shape is a captured baseline configuration (features, limits, edition, and Metadata API settings) of a source org, without its data or metadata. Use when the user asks to create/make/take an org shape, capture or replicate an org's configuration/edition/limits, list/show/view existing org shapes (including INACTIVE/superseded ones) or their IDs and status, or delete/remove org shapes for a source org. Requires a source org with Dev Hub and Org Shape for Scratch Orgs enabled. DO NOT TRIGGER for creating/checking/listing/deleting snapshots (use dx-org-snapshot-manage) or for creating scratch orgs (use dx-org-manage)."
 metadata:
   version: "1.0"
   domains: ["Developer Experience"]
@@ -33,7 +33,7 @@ Coordinates the full lifecycle of Salesforce org shapes — **create**, **list**
 ## Scope
 
 - **In scope**: Creating (`sf org create shape`), listing (`sf org list shape`), listing including inactive shapes for a specific source org (SOQL against `ShapeRepresentation`), and deleting (`sf org delete shape`) org shapes
-- **Out of scope**: Creating snapshots, creating scratch orgs (use `dx-org-manage`)
+- **Out of scope**: Creating/checking/listing/deleting snapshots (use `dx-org-snapshot-manage`), creating scratch orgs (use `dx-org-manage`)
 
 ---
 
@@ -136,7 +136,8 @@ See the example files referenced below for full response structures.
 
 | Need | Delegate to |
 |------|-------------|
-| Create a scratch org, or create/use a snapshot | `dx-org-manage` skill |
+| Create a scratch org, or create/use a snapshot to make one | `dx-org-manage` skill |
+| Create, check status of, list, or delete a snapshot itself | `dx-org-snapshot-manage` skill |
 
 ---
 

package/skills/education-cloud-domain-configure/references/gotchas-extended.md

@@ -21,3 +21,4 @@ Lower-frequency gotchas and toggle-write failure classes, split out of `SKILL.md
 | **Failure class — settings type invisible to Tooling/EntityDefinition but still MDAPI-writable** (e.g. Omnistudio Metadata, `OmniStudioSettings`, `fullName: OmniStudio`) | Metadata PUT write succeeds, but no GET/verify path exists via Tooling API — UI-confirmed only; if you encounter one of these, note it as write-succeeds-zero-verify-path rather than assuming failure |
 | **Failure class — type-level UPDATE block** (e.g. Timeline `TimelineSettings`, Video Calls `VideoCallsSettings`) | PUT returns HTTP 400 `UNSUPPORTED_OPERATION: "MetadataCrud does not support UPDATE on type: X"` — block is on the whole type, no `fullName` variant fixes it; manual UI only |
 | **Pattern — org preference API, not `IndustriesSettings`** (confirmed on Einstein Generative AI, `EinsteinGPTCopilotEnabled`) | Some toggles are Setup-Connect org preferences, not `IndustriesSettings` metadata fields — no `type`/`fullName`/`xmlRep`. Shape: `GET /services/data/v68.0/setup/org/preferences/<PrefName>` → `{"isPreferenceEnabled": bool}`; `PATCH` same path with `{"desiredState": true}` → response echoes post-write state. If a metadata PUT returns `FIELD_INTEGRITY_EXCEPTION: invalid at this location` for a plausible-looking element name, the field may not be on `IndustriesSettings` at all — try this org-preference path next before assuming manual-UI-only |
+| **Failure class — write-enabled `dispatch` MCP tool not connected/loaded** | Fall back to the `sf api request rest` CLI (via Bash) for the exact same READ/WRITE/cold-VERIFY calls before giving up to manual Setup UI — confirmed working in the same run where other datasets hit this identical MCP gap. Never report a toggle's state as "assumed default" or "pending admin confirmation" without trying this fallback first |

package/skills/experience-accessibility-validate/SKILL.md

@@ -11,7 +11,7 @@ metadata:
     - "design-systems-slds-validate"
     - "experience-lwc-generate"
 ---
-<!-- adk-managed-skill -->
+<!-- a11y-expert-managed-skill -->
 
 # Web Component Accessibility
 
@@ -47,16 +47,19 @@ Key Review Criteria:
 4. Component Library Usage
 
 - Assume that well-known component libraries (e.g., Salesforce Lightning, Material UI, Chakra UI) are accessible out of the box when correctly implemented. Unless they are used specifically in conflict with WCAG, library-provided components can be ignored for this review, as they are implemented in an accessible way beneath the abstraction.
+- Lightning base components (`lightning-input`, `lightning-combobox`, `lightning-textarea`, `lightning-icon`, and similar components) provide accessible labeling, ARIA, and error handling through dedicated attributes such as `label` and `alternative-text`. A `label` remains programmatic even with `variant="label-hidden"`; do not require a sibling or wrapper `<label>` to target the component. Navigation, button-icon, and other self-labeling base components likewise expose supplied label text as their accessible name and treat their internal icon as decorative. Do not report a missing association merely because that implementation is hidden inside the component.
+- The same self-labeling logic applies to **imported or custom control components in any framework** (React/JSX, Angular, Vue, Web Components), not only Lightning. A capitalized or imported component tag (`<Input>`, `<TextField>`, `<Button>`, `<Select>`, `<Checkbox>`, `<SearchField>`, and design-system wrappers from Material UI, Chakra, Radix, or an internal library) is **not** a bare HTML element — assume it renders its own accessible label, ARIA, and error handling beneath the abstraction (see the component-library grounding rule). When such a component is given a labeling prop — `label`, `aria-label`, `aria-labelledby`, `title`, or visible child text/`children` — treat it as already programmatically labeled and do **not** flag it for a missing `<label>`, a missing `for`/`id` association, or a missing accessible name. Only flag when **no** labeling prop or text is supplied, or the supplied value is clearly empty or nonsensical. Do not demand a native `<label for>` for a component whose internal control you cannot see.
+- Resolve dynamic `id` / `htmlFor` / `for` expressions before judging a label association. When a `<label htmlFor={X}>` (or `for={X}`) and its control's `id={X}` are bound to the **same expression** — the same variable, prop, `useId()` value, or template literal (e.g. both `htmlFor` and `id` set to the same interpolation such as `${id}-email`) — treat the association as **matching**, even though the literal string cannot be resolved at review time. A dynamic `id`/`htmlFor` pair is a mismatch only when the two expressions are demonstrably different. Do **not** flag identical dynamic `id`/`htmlFor` expressions as unmatched or mismatched labels.
 
-**Focus**: Provide actionable feedback to ensure the component meets the necessary WCAG accessibility requirements, avoiding extraneous feedback unrelated to the prompt's scope. Identify issues in code only if there is an immediate fix. You MUST conduct the review, and subsequently suggest the code fix that solves this issue.
+5. Source Interpretation
 
+- Resolve expressions according to the framework's binding semantics before judging them. Trace a dynamic value to every source available in that context. In React/JSX, an expression may reference local variables, props, hook results, or imported bindings; Vue, Svelte, and Astro expose their own template or script scopes. In an LWC template specifically, `{someValue}` resolves to a field, property, or getter on the component class (`.js` or `.ts`), including `@api` properties; module-level imported constants are not directly bindable. In Aura markup, follow the expression's value provider, such as `v.` or `c.`, to the corresponding component attribute or controller logic. Do not conclude that a value is undefined, empty, or missing until you have inspected the applicable source. In a diff, verify which side contains the corrected code rather than assuming that the change introduced the problem.
 
+**Focus**: Provide actionable feedback to ensure the component meets the necessary WCAG accessibility requirements, avoiding extraneous feedback unrelated to the prompt's scope. Identify issues in code only if there is an immediate fix. You MUST conduct the review, and subsequently suggest the code fix that solves this issue.
 
 ## Success Criteria Reviewers
 
-Identify which Success Criteria apply to the code under review, then open the reference files relevant to that code. Each reference is a
-self-contained reviewer with analysis framework, examples, and remediation
-guidance.
+Identify which Success Criteria apply to the code under review, then open the reference files relevant to that code. Each reference supplies criterion-specific analysis, examples, and remediation guidance; the review-wide rules above continue to apply.
 
 ### Perceivable