@salesforce/afv-skills 1.63.0 → 1.65.0

package/skills/automation-sandbox-post-copy-configure/references/flow_activation_path.md

@@ -0,0 +1,151 @@
+# Step G — Flow activation / deactivation (`Flows`)
+
+`Flows` entries in the post-copy config mutate
+`FlowDefinition.Metadata.activeVersionNumber` via the same
+compound-`Metadata` PATCH transport as Steps D-1/D-3, but Step D-2's
+mutation-key derivation does **not** apply — the mutation key is
+always the literal `activeVersionNumber`. Follow G-1 → G-4 below
+**instead of** Step D for `Flows` entries. Steps A + B still apply
+(`FlowDefinition` is the pinned sobject; Step B confirms the
+`Metadata` compound field exists on this org).
+
+## Fields shape
+
+Every `Flows` entry carries these keys under `Fields`:
+
+| Key | Meaning |
+|-----|---------|
+| `FlowApiName` | `DeveloperName` of the parent `FlowDefinition`. Required. |
+| `Action` | `"Activate"` or `"Deactivate"`. Required. |
+| `VersionNumber` | Integer. Required for `Activate` only when pinning a specific saved version; omit to activate the latest saved version. Ignored for `Deactivate`. |
+
+Reject `FlowApiName` that doesn't match `^[A-Za-z_][A-Za-z0-9_]*$`
+before any SOQL — the queries below interpolate it unescaped; a
+malformed name is a SOQL-injection risk. Fail-closed on mismatch
+(`API_NOT_IDENTIFIED`).
+
+## G-1 — Look up the FlowDefinition + current active version
+
+```bash
+FLOW_API_NAME='<Fields.FlowApiName>'
+SOQL="SELECT Id, DeveloperName, ActiveVersion.VersionNumber FROM FlowDefinition WHERE DeveloperName = '$FLOW_API_NAME'"
+sf data query --use-tooling-api --json --query "$SOQL" \
+  > /tmp/entry-<Slug>-flow-lookup.json
+ID=$(jq -r '.result.records[0].Id // empty' /tmp/entry-<Slug>-flow-lookup.json)
+CURRENT_ACTIVE=$(jq -r '.result.records[0].ActiveVersion.VersionNumber // empty' /tmp/entry-<Slug>-flow-lookup.json)
+```
+
+- Zero rows → `NOT_FOUND` (add Follow-ups bullet; skip PATCH).
+- `CURRENT_ACTIVE` is the currently-active version number, or empty
+  if the flow is inactive. `DeveloperName` is unique, so multiple rows
+  should not occur; guard with `AMBIGUOUS` if they do.
+
+## G-2 — Resolve target `activeVersionNumber` + apply pre-flight
+
+- If `Fields.Action == "Deactivate"`:
+  - Target = `null`.
+  - If `CURRENT_ACTIVE` is empty → record `ALREADY_INACTIVE`, skip
+    PATCH, add a Follow-ups bullet.
+- If `Fields.Action == "Activate"`:
+  - If `Fields.VersionNumber` is present → target = that integer.
+  - Otherwise → query the latest saved version:
+    ```bash
+    SOQL="SELECT VersionNumber FROM Flow WHERE DefinitionId = '$ID' ORDER BY VersionNumber DESC LIMIT 1"
+    sf data query --use-tooling-api --json --query "$SOQL" \
+      > /tmp/entry-<Slug>-flow-latest.json
+    TARGET=$(jq -r '.result.records[0].VersionNumber // empty' /tmp/entry-<Slug>-flow-latest.json)
+    ```
+    Empty result → `NOT_FOUND` (flow has no saved versions).
+  - If `CURRENT_ACTIVE == TARGET` → record `ALREADY_ACTIVE`, skip
+    PATCH, add a Follow-ups bullet.
+
+## G-3 — GET current Metadata, mutate, PATCH back
+
+Same compound-`Metadata` transport as Step D-3, with the mutation
+fixed to `activeVersionNumber`. Do NOT run
+`scripts/map-metadata-key.mjs` — the mutation key is always the
+literal `activeVersionNumber`. Preserve every other key from the GET
+below; overlay only `activeVersionNumber`. Never substitute
+`ActiveVersion`, `activeVersionId`, `Status`, or `IsActive` — they
+look like candidate keys but all fail with 400 or silent no-op.
+
+The GET returns the complete Tooling API record (`Id`, `attributes`,
+`Metadata`, …). Narrow with `?fields=Metadata` and extract the
+`Metadata` object with `jq '.Metadata'` **before** the Step D-3
+merge — the merge wraps its input as `{"Metadata": …}`, so if the
+raw record is piped in, non-metadata keys end up inside `Metadata`
+and the PATCH is rejected.
+
+```bash
+sf api request rest \
+  "/services/data/v<apiVersion>/tooling/sobjects/FlowDefinition/$ID?fields=Metadata" \
+  | jq '.Metadata' > /tmp/entry-$ID-meta.json
+
+# Build /tmp/entry-$ID-mutation.json with {"activeVersionNumber": <TARGET or null>},
+# merge with /tmp/entry-$ID-meta.json using `jq --slurpfile`, PATCH the
+# merged result. Full recipe: references/api_endpoints.md §Step D.
+```
+
+Dry-run: resolve the plan via G-1 + G-2; skip the G-3 GET + PATCH;
+record `DRY_RUN`. The plan prints the fixed mutation key
+(`activeVersionNumber`) and the resolved target without reading or
+mutating the current Metadata payload.
+
+## G-4 — Verify the change landed
+
+Re-run the G-1 SOQL and confirm `ActiveVersion.VersionNumber` matches
+the target (or is empty after Deactivate). Mismatch → `FAILED_VERIFY`.
+
+## Summary shape for a Flows entry
+
+The generic `Planned request:` block from SKILL.md's canonical output
+shape does **not** apply to a Flows entry — the Flows path dispatches
+across four distinct sub-steps (SOQL lookup, target resolution, GET+
+PATCH, verify), so the summary must record evidence that each
+sub-step ran, not just the final PATCH body. Replace the
+`Planned request:` block with the narrative below, keeping the
+single-row phase table and the Totals / Follow-ups sections unchanged.
+
+For each Flows entry's phase block, emit (in this order):
+
+1. A one-line route header:
+   ```text
+   Route: **Step G — Flows (compound-`Metadata` PATCH with fixed `activeVersionNumber` mutation)**. Mutation key is fixed, NOT derived from the describe payload — `scripts/map-metadata-key.mjs` is skipped for Flows.
+   ```
+
+2. `Pre-flight lookup (G-1):` — the G-1 SOQL and the single-row result
+   (`ActiveVersion.VersionNumber = <value or null>`), ending with the
+   decision (`Not already active → proceed to G-2` /
+   `ALREADY_INACTIVE short-circuit` / `AMBIGUOUS` / `NOT_FOUND`).
+
+3. `Target resolution (G-2):` — the branch taken (`Action = Activate`
+   with `Fields.VersionNumber` present / absent → latest-version SOQL;
+   `Action = Deactivate` → target `null`), the resolved target
+   `activeVersionNumber`, and a one-line comparison vs the pre-flight
+   state justifying no short-circuit. For `Activate` without
+   `Fields.VersionNumber`, include the latest-version SOQL verbatim
+   and its returned `VersionNumber = <N>`.
+
+4. `Request executed (G-3):` — the GET and PATCH as **two separate
+   bullets** (not a Method/Path/Body sub-structure), each with the
+   full Tooling path, then the PATCH body as
+   `{ "Metadata": { …retrieved keys preserved…, "activeVersionNumber": <target> } }`,
+   then the `204 No Content` response line. On dry-run, rename this
+   section to `Planned request (G-3, dry-run):`, drop the GET bullet,
+   render the PATCH body as the fixed-key-only
+   `{ "Metadata": { "activeVersionNumber": <target> } }` (no retrieved
+   keys — the GET is skipped), omit the response line, row Outcome is
+   `DRY_RUN`, and skip section 6 below.
+
+5. The single-row phase table (unchanged from SKILL.md's canonical
+   shape; `Describe` column may be `—` for Flows since Step B's
+   describe is prod-parity only).
+
+6. `Read-back verification (G-4):` — the re-run G-1 SOQL and the
+   observed `ActiveVersion.VersionNumber` (or `ActiveVersion = null`
+   after Deactivate), confirming the mutation landed.
+
+Short-circuit cases (`ALREADY_ACTIVE` / `ALREADY_INACTIVE` /
+`NOT_FOUND` / `AMBIGUOUS` / `API_NOT_IDENTIFIED`) emit G-1 (and G-2
+if the short-circuit is only visible after target resolution) and
+stop — skip G-3, G-4, and the row's `HTTP` column renders `—`.

package/skills/automation-sandbox-post-copy-configure/references/scheduled_apex_path.md

@@ -131,15 +131,61 @@ Skip F-4 entirely in dry-run (nothing to verify).
 
 ## Summary shape for a Step F entry
 
-Reuse the phase table from the canonical output shape:
-
-- `Sobject` column reads `CronTrigger`.
-- `Describe` column reads `—` (no describe probe on this route).
-- "Planned request" / "Request executed" is the anonymous Apex snippet
-  path (`/tmp/entry-<Slug>.apex`) and its contents inline, not a PATCH
-  path/body.
-- `HTTP` column reads `—` (no direct HTTP status; `sf apex run` bundles
-  compile+execute into one response).
+The generic `Planned request:` block from SKILL.md's canonical output
+shape does **not** apply to a ScheduledApex entry — the Step F path
+dispatches across four distinct sub-steps (pre-flight SOQL, snippet
+build, `sf apex run`, verify SOQL), so the summary must record
+evidence that each sub-step ran, not just the final `sf apex run`.
+Replace the `Planned request:` block with the labeled narrative
+below, keeping the single-row phase table and the Totals /
+Follow-ups sections unchanged.
+
+For each ScheduledApex entry's phase block, emit (in this order):
+
+1. A one-line route header:
+   ```text
+   Route: **Step F — Scheduled Apex (anonymous Apex)**. No describe probe on this route; `CronTrigger` is read-only.
+   ```
+
+2. `Pre-flight AMBIGUOUS check:` — the F-1 SOQL and the single-row
+   `totalSize` result (never a bulk count claim), ending with the
+   decision (`totalSize = 0 → proceed to F-2` /
+   `AMBIGUOUS short-circuit — N existing CronTrigger rows`). Emit the
+   SOQL verbatim, with `JobName` single-quoted as it appeared on the
+   wire (post-SOQL-escape); do not paraphrase.
+
+3. `Request executed:` — the F-2/F-3 artifacts as **three separate
+   bullets** (not Method/Path/Body sub-structure):
+   - `Snippet path:` — the `/tmp/entry-<Slug>.apex` path F-2 wrote.
+   - `Snippet body:` — the exact one-line
+     `System.schedule('<JobName>', '<CronExpression>', new <ApexClassName>());`
+     string F-2 produced, with the same single-quote-escaping F-2
+     applied (not the pre-escape input).
+   - `Command:` — the exact
+     `sf apex run --file /tmp/entry-<Slug>.apex --json` invocation
+     F-3 ran.
+   On dry-run, rename this section to `Planned request (F-2, dry-run):`,
+   keep only the `Snippet path:` and `Snippet body:` bullets (omit
+   `Command:` — F-3 is skipped), row Outcome is `DRY_RUN`, and skip
+   section 5 below.
+
+4. The single-row phase table (unchanged from SKILL.md's canonical
+   shape):
+   - `Sobject` column reads `CronTrigger`.
+   - `Describe` column reads `—` (no describe probe on this route).
+   - `HTTP` column reads `—` (no direct HTTP status; `sf apex run`
+     bundles compile + execute into one response).
+
+5. `Read-back verification:` — the F-4 SOQL verbatim and the
+   observed row (`N row(s) with CronExpression = "<value>"`),
+   confirming the schedule landed. On `0 rows → FAILED_VERIFY`
+   emit the zero-row result; on `CronExpression mismatch →
+   FAILED_VERIFY` emit both the expected and observed values.
+
+Short-circuit cases (`AMBIGUOUS` / `API_NOT_IDENTIFIED` /
+`FAILED` at F-2 or F-3 / `FAILED_VERIFY`) emit F-1 (and F-2/F-3 if
+the failure is visible later) and stop — skip F-4 and the row's
+`HTTP` column renders `—`.
 
 ## Dry-run recap
 

package/skills/automotive-cloud-appraisal-management-settings-configure/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: automotive-cloud-appraisal-management-settings-configure
+description: "Use this skill when users want to toggle two industry-cloud org preferences via the SetupApiFamily Connect API: parent AppraisalManagementEnabled and child AutomotiveComponentsForAppraisalMgmtEnabled. Trigger when users mention appraisal, management, settings, appraisal management settings."
+metadata:
+  version: "1.0"
+---
+
+# Managing Appraisal Management Settings
+
+## When to Use This Skill
+
+Toggle two industry-cloud org preferences via the SetupApiFamily Connect API: parent AppraisalManagementEnabled and child AutomotiveComponentsForAppraisalMgmtEnabled. Reads + writes are per-pref single-call. Child write is conventionally gated on parent=true AND Automotive Cloud enabled or orgHasAutomotiveDealerEssentials (LWC-rendered, server allows write regardless). Setup-node access requires Customize Application or System Administrator.
+
+## Workflow
+
+Read isOrgPreferenceEnabled_wire_3 (per-pref iteration over orgPreferences), then setOrgPreferences_1 (parent) and/or setOrgPreferences_2 (child) — independent server-side. Verify-* steps re-read via checkPreference. Child write conventionally requires parent=true + IndustriesAutomotive perm; server accepts regardless. 403 = caller lacks Customize Application.
+
+## Critical Constraints
+
+**Preconditions:**
+
+- Org has the Appraisal Management access license/perm — gates the Setup node's visibility and accessibility. Without it the AppraisalManagementSettings page is not reachable. (check: `Appraisal Management access`)
+- Caller has Customize Application permission or is a System Administrator. Derived from the manifest's Customize Application permission access predicate; unauthorized callers get 403 from checkPreference and updatePreference on this Setup family. (check: `Customize Application permission`)
+- Conditional on the child setOrgPreferences_2 step: org has Automotive Cloud enabled or Automotive Dealer Essentials access. The LWC hides the child toggle without one of these (appraisalManagementPref.js line 51); the Connect endpoint itself accepts the write regardless, but persisting the child pref while the parent feature lacks Automotive coverage is unconventional and may have no UI surface. (check: `Automotive Cloud enabled OR Automotive Dealer Essentials access`)
+- Conditional on the child setOrgPreferences_2 step: parent AppraisalManagementEnabled is already true. The LWC only renders the child toggle when the parent pref reads back true (showAutoComponentsChildPrefComp gate, appraisalManagementPref.js line 51).
+
+## Operations Reference
+
+Operations grouped by purpose. Use these as the building blocks for the workflows above.
+
+### Summary
+
+| Operation | Purpose | Status | Call | Depends on |
+|-----------|---------|--------|------|------------|
+| `isOrgPreferenceEnabled_wire_3` | read | — | `/services/data/v66.0/setup/org/preferences/{preferenceName}` | — |
+| `setOrgPreferences_1` | write | — | `/services/data/v66.0/setup/org/preferences/{preferenceName}` | `isOrgPreferenceEnabled_wire_3` |
+| `setOrgPreferences_2` | write | — | `/services/data/v66.0/setup/org/preferences/{preferenceName}` | `isOrgPreferenceEnabled_wire_3`, `setOrgPreferences_1` |
+
+### Read operations
+
+#### `isOrgPreferenceEnabled_wire_3`
+
+Calls checkPreference once per inputs.orgPreferences entry. Returns isPreferenceEnabled (boolean) per call; agent assembles a name->boolean map locally. 403 if caller lacks Customize Application; 404 on unknown preferenceName.
+
+**Call:** `/services/data/v66.0/setup/org/preferences/{preferenceName}`
+
+**Output:** Per call: PreferenceCheckOutputRepresentation {isPreferenceEnabled: boolean} where true means the named org pref is enabled. The agent calls checkPreference once per entry in inputs.orgPreferences and assembles a name->boolean map locally.
+
+### Write operations
+
+#### `setOrgPreferences_1`
+
+PATCH preferenceName=AppraisalManagementEnabled, body {desiredState: boolean}. Response echoes isPreferenceEnabled (in-line verify). Disabling parent hides child UI toggle but does not auto-disable it. 403 lacks Customize Application.
+
+**Call:** `/services/data/v66.0/setup/org/preferences/{preferenceName}`
+
+**Depends on:** `isOrgPreferenceEnabled_wire_3`
+
+**Output:** PreferenceCheckOutputRepresentation with isPreferenceEnabled boolean — server echo of the post-write state. Agents can use this echo as an in-line verify, or re-read via the isOrgPreferenceEnabled_wire_3 step for an explicit confirmation.
+
+#### `setOrgPreferences_2`
+
+PATCH preferenceName=AutomotiveComponentsForAppraisalMgmtEnabled, body {desiredState: boolean}. Response echoes isPreferenceEnabled (in-line verify). Conventionally requires parent AppraisalManagementEnabled=true and Automotive Cloud/Dealer Essentials access; server accepts write regardless. 403 = caller lacks Customize Application.
+
+**Call:** `/services/data/v66.0/setup/org/preferences/{preferenceName}`
+
+**Depends on:** `isOrgPreferenceEnabled_wire_3`, `setOrgPreferences_1`
+
+**Output:** PreferenceCheckOutputRepresentation with isPreferenceEnabled boolean — server echo of the post-write state. Verified working: PATCH returns 200 with {isPreferenceEnabled: true/false} regardless of Automotive license state.

package/skills/automotive-cloud-dealer-essentials-configure/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: automotive-cloud-dealer-essentials-configure
+description: "Use this skill when users want to toggle two Automotive org preferences via SetupMetadata batch ops: `DealerEssentialsForAutomotiveEnabled` (master) and `IndustriesAutomotiveSchedulerEnabled` (subordinate). Trigger when users mention dealer, essentials, automotive, settings, dealer essentials for automotive settings."
+metadata:
+  version: "1.0"
+---
+
+# Managing Dealer Essentials For Automotive Settings
+
+## When to Use This Skill
+
+Toggle two Automotive org preferences via SetupMetadata batch ops: `DealerEssentialsForAutomotiveEnabled` (master) and `IndustriesAutomotiveSchedulerEnabled` (subordinate). Read: `GET .../is-org-preference-enabled?orgPreferences=[...]` → `Map<String, Boolean>`. Write: `PATCH .../set-org-preference` body `{orgPreferences: {<api-name>: <bool>}}` (multi-pref atomic). Server-gated by View Setup; master/subordinate gating is UI-only — server permits the scheduler write regardless of master state.
+
+## Critical Constraints
+
+**Preconditions:**
+
+- View Setup required — a class-level `View Setup permission` access guard gates both ops. (check: `View Setup permission`)
+- Org must hold the Automotive Cloud / Industries Automotive license that exposes `DealerEssentialsForAutomotiveEnabled`; without it the prefs persist but feature surfaces stay dark.
+
+## Verification Checklist
+
+After every write operation, confirm the effect by re-reading state:
+
+- After `setOrgPreferences_1`, `write-org-preference`: call `verify-is-org-preference-enabled` (`GET /headless/invoke/platform/setup/setup-metadata/is-org-preference-enabled`)
+
+## Operations Reference
+
+Operations grouped by purpose. Use these as the building blocks for the workflows above.
+
+### Summary
+
+| Operation | Purpose | Status | Call | Depends on |
+|-----------|---------|--------|------|------------|
+| `isOrgPreferenceEnabled_wire_3` | read | — | `checkPreference` | — |
+| `setOrgPreferences_1` | write | — | `updatePreference` | `isOrgPreferenceEnabled_wire_3` |
+| `write-org-preference` | write | — | `PATCH /headless/invoke/platform/setup/setup-metadata/set-org-preference` | `isOrgPreferenceEnabled_wire_3`, `setOrgPreferences_1` |
+| `verify-is-org-preference-enabled` | verify | — | `GET /headless/invoke/platform/setup/setup-metadata/is-org-preference-enabled` | `setOrgPreferences_1`, `write-org-preference` |
+
+### Read operations
+
+#### `isOrgPreferenceEnabled_wire_3`
+
+Batch-read both Automotive org preferences (`DealerEssentialsForAutomotiveEnabled`, `IndustriesAutomotiveSchedulerEnabled`) via SetupMetadata `isOrgPreferenceEnabled`. Returns `Map<String, Boolean>` keyed by api-name. Requires View Setup.
+
+**Call:** `checkPreference`
+
+**Output:** `Map<String, Boolean>` keyed by each requested org-preference api-name; value is the current enabled state under the SetupMetadata permission frame. Unknown api-names are silently omitted from the result map.
+
+### Write operations
+
+#### `setOrgPreferences_1`
+
+Write `DealerEssentialsForAutomotiveEnabled` via SetupMetadata `setOrgPreference` (PATCH; void return). Body shape `{orgPreferences: {DealerEssentialsForAutomotiveEnabled: <bool>}}`. Endpoint accepts multiple prefs in one call. Requires View Setup.
+
+**Call:** `updatePreference`
+
+**Depends on:** `isOrgPreferenceEnabled_wire_3`
+
+#### `write-org-preference`
+
+Write `IndustriesAutomotiveSchedulerEnabled` via SetupMetadata `setOrgPreference` (PATCH; void). Body `{orgPreferences: {IndustriesAutomotiveSchedulerEnabled: <bool>}}`. Requires View Setup. No server-side master/subordinate gating.
+
+**Call:** `PATCH /headless/invoke/platform/setup/setup-metadata/set-org-preference`
+
+**Depends on:** `isOrgPreferenceEnabled_wire_3`, `setOrgPreferences_1`
+
+### Verify operations
+
+#### `verify-is-org-preference-enabled`
+
+Read-back via SetupMetadata `isOrgPreferenceEnabled` to confirm the preceding writes took effect. Same endpoint as page-load read; one call covers both prefs.
+
+**Call:** `GET /headless/invoke/platform/setup/setup-metadata/is-org-preference-enabled`
+
+**Depends on:** `setOrgPreferences_1`, `write-org-preference`
+
+**Output:** `Map<String, Boolean>` confirming each pref's persisted state matches the value just written.