@salesforce/afv-skills 1.51.0 → 1.52.0

package/skills/field-service-sobject-create-configure/SKILL.md

@@ -5,29 +5,48 @@ user-invocable: false
 metadata:
   version: "1.0"
   domains: ["Field Service"]
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
 ---
 
+# Managing Sfs Sobject Create
+
+## When to Use This Skill
+
+Create sObject records via Headless 360 REST API. Describes the flow (describe → query → create), Field Service data model DAG, field requirements, insertion order, and common pitfalls. Reference when creating Skill, WorkType, SkillRequirement, or other Field Service sObjects.
+
+## Workflow
+
 # Create an sObject record via headless-360
 
 **Be helpful** — understand business context before creating records. Consider the business domain of the sObject being created and iterate through short, structured questions (ask/why/impact) until no ambiguities remain that would change what gets created. Skip questions when answers are already obvious from context or existing data.
 
 ## Flow
 
-1. **Describe** — `dispatch_readonly` GET `/services/data/v67.0/sobjects/<SObject>/describe`
-2. **Query existing records** — learn the org's shape before writing.
-   `dispatch_readonly` GET `/services/data/v67.0/query`,
+### Phase 1: **Describe** — `dispatch_readonly` GET `/services/data/v67.0/sobjects/<SObject>/describe`
+
+
+
+### Phase 2: **Query existing records** — learn the org's shape...
+
+`dispatch_readonly` GET `/services/data/v67.0/query`,
    `queryParams.q = "SELECT <required + picklist fields> FROM <SObject> ORDER BY CreatedDate DESC LIMIT 20"`.
    Use it to: match naming/value conventions, see which optional fields are actually populated,
    catch duplicates, and confirm write access before spending a create.
-3. **Create** — `dispatch` POST to create records. Single record → `/services/data/v67.0/sobjects/<SObject>` with body. Multiple related records (DAG) → `/services/data/v67.0/composite/graph` to batch-create with dependency references in one transaction. Success → `201` with id(s). Failure → non-2xx with `errorCode` + `message` — act on that.
+
+### Phase 3: **Create** — `dispatch` POST to create records. Single...
+
+
 
 ## Data model DAG
 
-These examples show Field Service relationship patterns, but the same approach applies to any sObject based on its data shape:
+Example (Field Service junction pattern — same pattern applies to any sObject DAG based on the data shape):
 
 ```text
-Skill + WorkType → SkillRequirement    WorkType + Product2 → ProductRequired
-OperatingHours → ServiceTerritory + TimeSlot
+Skill (0C5)    WorkType (08q)    ← roots (parallel)
+    └──────────┬──────────┘
+       SkillRequirement (0Hx)     ← junction (last)
 ```
 
 ## Fields and insertion order
@@ -54,3 +73,199 @@ to see conventions and dupes. Then create with the derived body, e.g.
 { "url": "/services/data/v67.0/sobjects/WorkType", "method": "POST",
   "body": { "Name": "Standard Repair", "EstimatedDuration": 2 } }
 ```
+
+─────
+**Runtime context (Headless 360 / agentic):** When this skill runs in the Headless 360 / agentic context, prefer the platform dispatch tool (``dispatch`` in the hosted Headless 360 MCP; ``dispatch`` in the local-dev MCP) over CLI tools (``sf project deploy``, ``sfdx``, shell commands) when possible. The operations available to you are listed below in ``steps:``; each has been verified against the live org. Call the dispatch tool against the canonical paths. CLI fallback is acceptable only when no API path exists for a given capability.
+
+## Critical Constraints
+
+**Preconditions:**
+
+- Target sObject is createable and not on the sObject-REST block list. (check: `GET /services/data/v67.0/sobjects/{N}/describe returns `createable: true` at the top level. A `CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY` on POST means the sObject blocks base REST writes (e.g. `ExternalDataSource`, `CustomPermission`) — switch to Tooling or Metadata API.`)
+- Gateway user has object CRUD + relevant FLS for the required createable fields. (check: `400 / 403 with `INSUFFICIENT_ACCESS_OR_READONLY` on POST → CRUD/FLS gap, not a payload bug. Grant the user's profile / permset the Create on the entity and Edit-access on every field in the body.`)
+- For composite/graph transactions, the caller has independently topo-sorted parents before children within each graph node's `records`. (check: ``referenceId`s used with `@{...}` MUST refer to a record earlier in the same graph. Wrong ordering surfaces as `INVALID_REFERENCE_ID` on the child node, and the entire graph rolls back atomically.`)
+
+## Operations Reference
+
+Operations grouped by purpose. Use these as the building blocks for the workflows above.
+
+### Summary
+
+| Operation | Purpose | Status | Call | Depends on |
+|-----------|---------|--------|------|------------|
+| `describe-sobject` | read | — | `GET /services/data/v67.0/sobjects/{SObjectName}/describe` | — |
+| `query-existing-records` | read | — | `GET /services/data/v67.0/query` | `describe-sobject` |
+| `create-sobject-record` | write | — | `POST /services/data/v67.0/sobjects/{SObjectName}` | `describe-sobject` |
+| `composite-graph-create` | write | — | `POST /services/data/v67.0/composite/graph` | `describe-sobject` |
+| `update-sobject-record` | write | — | `PATCH /services/data/v67.0/sobjects/{SObjectName}/{Id}` | `create-sobject-record` |
+| `delete-sobject-record` | write | — | `DELETE /services/data/v67.0/sobjects/{SObjectName}/{Id}` | — |
+
+### Dependency graph
+
+```mermaid
+graph TD
+  describe_sobject["describe-sobject (read)"]
+  query_existing_records["query-existing-records (read)"]
+  create_sobject_record["create-sobject-record (write)"]
+  composite_graph_create["composite-graph-create (write)"]
+  update_sobject_record["update-sobject-record (write)"]
+  delete_sobject_record["delete-sobject-record (write)"]
+  describe_sobject --> query_existing_records
+  describe_sobject --> create_sobject_record
+  describe_sobject --> composite_graph_create
+  create_sobject_record --> update_sobject_record
+```
+
+### Read operations
+
+#### `describe-sobject`
+
+Fetch the field catalog for {SObjectName}. Scan `fields[]` for
+`createable:true`; hard-required fields are those also with
+`nillable:false` and `defaultedOnCreate:false`. `type:"reference"`
+fields are FKs — hard edges when `nillable:false`. Base sObject
+CRUD is intentionally OUT of the discover corpus (skill §Pitfalls);
+agents must skip discover and call describe directly.
+
+**Call:** `GET /services/data/v67.0/sobjects/{SObjectName}/describe`
+
+**Inputs:**
+
+- `SObjectName` *(`string`)* — API name of the sObject (e.g. WorkType, Skill, SkillRequirement). Path segment.
+
+**Output:** SObjectDescribeSObjectResult. Load-bearing keys: `createable`, `updateable`, `deletable`, `fields[]` (each with `name`, `type`, `createable`, `nillable`, `defaultedOnCreate`, `referenceTo[]`, `picklistValues[]`). Payload is large (>60KB for WorkType) — filter to `createable:true` fields before reasoning.
+
+#### `query-existing-records`
+
+Warm-read a small window of existing rows to match naming
+conventions, spot dupes, and confirm write access before spending
+a create. Skill §Flow.2 suggested SOQL:
+`SELECT <required + picklist fields> FROM <SObject>
+ORDER BY CreatedDate DESC LIMIT 20`.
+
+**Call:** `GET /services/data/v67.0/query`
+
+**Inputs:**
+
+- `q` *(`string`)* — SOQL query. Pass via `queryParams.q` (URL-encoded on the wire). LIMIT 20 or fewer is the recommended window for convention scanning.
+
+**Depends on:** `describe-sobject`
+
+**Output:** `{totalSize, done, records: [<row>]}`. `records[]` is the shape an agent scans for conventions. `done:false` + `nextRecordsUrl` surface when > 200 rows — irrelevant at LIMIT 20.
+
+### Write operations
+
+#### `create-sobject-record`
+
+Create ONE record. Body carries only fields that were
+`createable:true` on describe. For DAGs (parents + children +
+junctions), prefer composite/graph so all rows land atomically
+in one transaction. 201 → `{id, success, errors:[]}`; non-2xx
+returns `[{errorCode, message, fields:[]}]`.
+
+**Call:** `POST /services/data/v67.0/sobjects/{SObjectName}`
+
+**Inputs:**
+
+- `SObjectName` *(`string`)* — API name of the sObject (path segment).
+- `body` *(`object`)* — Field/value map. Only include fields with `createable:true` on describe; omit `defaultedOnCreate:true` fields (the platform fills them).
+
+**Depends on:** `describe-sobject`
+
+**Output:** 201 → `{id: "<15/18-char id>", success: true, errors: []}`. 4xx → array of `{errorCode, message, fields}`.
+
+**Rollback:** delete-sobject-record
+
+**Notes:** ERROR CONTRACT:
+- `CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY` → sObject blocks base
+  REST writes; switch to Tooling / Metadata API. Common for
+  `ExternalDataSource`, `CustomPermission`.
+- `INSUFFICIENT_ACCESS_OR_READONLY` → CRUD/FLS/sharing gap on
+  the gateway user; don't retry the same body.
+- `REQUIRED_FIELD_MISSING` → re-check describe filter (some
+  fields are createable+nillable:false only in specific record
+  types).
+- `INVALID_FIELD_FOR_INSERT_UPDATE` → field is not
+  `createable:true`; drop from body.
+
+#### `composite-graph-create`
+
+Atomically create a DAG of related records in one transaction.
+Skill §Data-model-DAG example: Skill + WorkType (roots) →
+SkillRequirement (junction). Use `referenceId` on each record
+and `@{parentRef.id}` in a child's FK field to bind at write
+time. Success returns 200 with per-node compositeResponse[]
+entries carrying per-child 201s. Any failure rolls back the
+ENTIRE graph.
+
+**Call:** `POST /services/data/v67.0/composite/graph`
+
+**Inputs:**
+
+- `body` *(`object`)* — `{graphs: [{graphId, compositeRequest: [{referenceId,
+method:"POST", url:"/services/data/v67.0/sobjects/<N>",
+body:{...}}, ...]}]}`. Multiple graphs may share one call;
+each isolates atomicity.
+
+**Depends on:** `describe-sobject`
+
+**Output:** 200 → `{graphs: [{graphId, graphResponse: {compositeResponse: [{body:{id, success, errors}, httpHeaders, httpStatusCode, referenceId}]}, isSuccessful}]}`. `isSuccessful:false` + per-child 4xx bodies on any failure.
+
+**Rollback:** delete-sobject-record
+
+**Notes:** ERROR CONTRACT:
+- `INVALID_REFERENCE_ID` → child references a `referenceId`
+  that appears LATER in the array or doesn't exist. Topo-sort
+  the compositeRequest[] parents-first.
+- `LIMIT_EXCEEDED` → composite/graph caps at 500 records per
+  graph and 75 graphs per call.
+- `MIXED_DML_OPERATION` → **the graph mixes setup-object
+  sObjects (e.g. `Skill`, `Group`, `User`, `Permission*`) with
+  non-setup sObjects (e.g. `WorkType`, `Account`, `Contact`)
+  in one transaction — the platform forbids this even inside
+  composite/graph.** Split into two calls: create setup-side
+  in call 1, capture the id, then create non-setup-side +
+  junction referencing that id in call 2. The skill's
+  Skill+WorkType+SkillRequirement example REQUIRES this split.
+- Any HTTP 4xx on ANY child → the graph's entire
+  compositeResponse rolls back; sibling children report
+  `PROCESSING_HALTED` and DELETE cleanup is unnecessary for
+  a failed graph.
+
+#### `update-sobject-record`
+
+Field-level update on an existing record. Use for late-bound
+`nillable:true` reference attachment (skill §Fields-and-
+insertion-order) or corrections. PATCH is field-merge, not
+full-replacement: only fields in the body change; omitted
+fields are untouched. 204 on success (no response body).
+
+**Call:** `PATCH /services/data/v67.0/sobjects/{SObjectName}/{Id}`
+
+**Inputs:**
+
+- `SObjectName` *(`string`)*
+- `Id` *(`string`)* — 15- or 18-char record id (path segment).
+- `body` *(`object`)* — Field/value map. Only include fields with `updateable:true` on describe.
+
+**Depends on:** `create-sobject-record`
+
+**Output:** 204 No Content on success. 4xx → same `[{errorCode, message, fields}]` shape as POST.
+
+#### `delete-sobject-record`
+
+Delete a record. Rollback target for create-sobject-record
+(single) and composite-graph-create (children where the
+transaction succeeded but a downstream verify failed).
+204 on success. Note: composite/graph atomically rolls back
+on failure — DELETE is only needed after a SUCCESSFUL graph
+that a later validation rejects.
+
+**Call:** `DELETE /services/data/v67.0/sobjects/{SObjectName}/{Id}`
+
+**Inputs:**
+
+- `SObjectName` *(`string`)*
+- `Id` *(`string`)*
+
+**Output:** 204 No Content. 404 → id already gone (idempotent); treat as success.

package/skills/field-service-voice-to-form-configure/SKILL.md

@@ -29,7 +29,7 @@ This skill walks the complete setup for both, in the order Salesforce documents
 The skill is idempotent. Re-running on an already-configured org applies zero changes.
 
 > **Runtime contract:** every org interaction in this skill is a REST call
-> dispatched through the Codey runtime (`execute_api` locally / the hosted
+> dispatched through the Codey runtime (`dispatch` locally / the hosted
 > Headless 360 MCP in shared surfaces). This skill has **no dependency on the
 > execution environment** — no `sf` CLI, no shell scripts, no local Python, no
 > `jq`, no temp files, no metadata deploy, no Apex. Detection is a set of REST
@@ -44,7 +44,7 @@ The skill is idempotent. Re-running on an already-configured org applies zero ch
 
 ## Platform Notes
 
-- All API paths use `vXX.0` — pin to the org's **current** API version (query `GET /services/data` and use the highest `version`), NOT a fixed floor. This matters for the Step 3 feature test specifically: the `PermissionsFieldServiceVoiceTo*` describe columns only surface at a recent API version. On a live org the columns were **absent** from the `PermissionSet` describe at v62.0/v64.0 but **present** at v68.0 — pinning to an old version produces a false "feature not licensed → Stop" negative. Use the org's latest version so the describe reflects the beta perms. v62.0 is a hard floor only (the V2F Beta assumes a recent release); it is not a safe version for the describe test.
+- All API paths use `vXX.0` — pin to the org's current API version (v62.0 or later; the V2F Beta assumes a recent release).
 - Endpoints marked **Tooling** dispatch to `/services/data/vXX.0/tooling/...`; the rest are the core Data API (`/services/data/vXX.0/...`).
 - The Codey runtime resolves and refreshes the connected org and mints tokens on demand — this skill never manages org aliases, instance URLs, or access tokens.
 - A few setup steps are genuinely clicks-only in **Setup** (the Einstein base-setup wizard org pref, the per-form LLM Targetable flag). For those the skill surfaces the exact Setup deeplink for the admin to click; it never tries to script them.
@@ -76,7 +76,7 @@ Before running the setup sequence, confirm all of the following:
 
 ## Setup Sequence
 
-Run steps in order. Each step reads the org state before it writes; if a precondition fails, the step surfaces the failure and stops without mutating the org. Every read and write below is a single `execute_api` call.
+Run steps in order. Each step reads the org state before it writes; if a precondition fails, the step surfaces the failure and stops without mutating the org. Every read and write below is a single `dispatch` call.
 
 ### Step 0: Detect provisioning state and route
 
@@ -196,10 +196,10 @@ If `Metadata.enableLsdkMode` is already `true`, LDS is on — skip to Step 1.5.
 **1b. PATCH the full `Metadata` back with `enableLsdkMode: true`** — `PATCH /services/data/vXX.0/tooling/sobjects/FieldServiceSettings/{Id}`:
 
 ```json
-{ "FullName": "FieldService", "Metadata": { "...all sibling keys from the GET...", "enableLsdkMode": true } }
+{ "Metadata": { "...all sibling keys from the GET...", "enableLsdkMode": true } }
 ```
 
-`FullName` is **required** on a Tooling `Metadata` PATCH — omitting it 400s with `FIELD_INTEGRITY_EXCEPTION` "Full name must be specified to update metadata" (verified against a live org). For the `FieldServiceSettings` singleton `FullName` is the literal `"FieldService"`; echo back the `FullName` returned by the 1a read. Send the **entire** `Metadata` object read in 1a with only `enableLsdkMode` flipped — a partial body nulls the omitted org prefs (`fieldServiceOrgPref`, `enableWorkOrders`, the search-field arrays, etc.). A 204 is success.
+Send the **entire** `Metadata` object read in 1a with only `enableLsdkMode` flipped — a partial body nulls the omitted org prefs (`fieldServiceOrgPref`, `enableWorkOrders`, the search-field arrays, etc.). A 204 is success.
 
 **1c. Verify it actually flipped** — re-run the 1a Tooling read and confirm `Metadata.enableLsdkMode == true`. This guards the rare SDO/trial-org case where a write reports success but the flag stays false. If it did not flip, surface the Setup deeplink for the admin to toggle it by hand:
 
@@ -249,7 +249,7 @@ Most common SDO/trial-org symptom: PSLs all assigned, EinsteinSetup page exists,
 but the runtime entitlement was never turned on. 'Turn On Einstein' flips it.
 ```
 
-**1.5c. Re-probe after the admin completes the wizard.** Re-run the 1.5a `execute_api` call. Do not move on until it returns `promptRecords`.
+**1.5c. Re-probe after the admin completes the wizard.** Re-run the 1.5a `dispatch` call. Do not move on until it returns `promptRecords`.
 
 ### Step 2: Enable the Voice to Record Edit org switch
 
@@ -268,13 +268,13 @@ V2RE's org-level switch lives on `FieldServiceMobileSettings`, a **regular sObje
 
 A 201 returns the new row Id (which already satisfies Step 2b — skip the PATCH).
 
-**2b. Flip `IsShowEditFullRecord` to true** on the existing row — `PATCH /services/data/vXX.0/sobjects/FieldServiceMobileSettings/{Id}`:
+**2b. Flip `IsShowEditFullRecord` (and `IsDefault`) to true** on the existing row — `PATCH /services/data/vXX.0/sobjects/FieldServiceMobileSettings/{Id}`:
 
 ```json
-{ "IsShowEditFullRecord": true }
+{ "IsShowEditFullRecord": true, "IsDefault": true }
 ```
 
-A 204 is success. **Do NOT include `IsDefault` in the PATCH body** — `IsDefault` is a create-only field and is *not updateable* on an existing row; sending it 400s with `INVALID_FIELD_FOR_INSERT_UPDATE` on `IsDefault` (verified against a live org). Set `IsDefault` only at create time via the 2a POST. If the existing row you're patching is not already the default (`IsDefault = false`) and you need it to be, you cannot flip it in place — the toggle then takes effect only on profiles explicitly mapped to this settings row via `MobileSettingsAssignment`; the simplest path for a pilot is to create the default row via 2a instead. Re-read the row (Step 0 diagnostic 4) to confirm `IsShowEditFullRecord` is `true`. The PATCH is idempotent: re-sending the same value returns 204 and changes nothing.
+A 204 is success. Re-read the row (Step 0 diagnostic 4) to confirm both fields are `true`. Without `IsDefault = true`, the toggle takes effect only on profiles explicitly mapped to this settings row via `MobileSettingsAssignment` — `IsDefault = true` is the simplest path for a pilot. The PATCH is idempotent: re-sending the same values returns 204 and changes nothing.
 
 > **What the user sees on-device.** Per Salesforce help (`mfs_actions_order.xml`): once `IsShowEditFullRecord = true` and the user has Edit access to the object, **Edit Work Order**, **Edit Work Order Line Item**, and **Edit Service Appointment** appear in the Actions launcher on the Work Order Overview screen, after Quick Actions. The mobile app caches the settings — the technician must log out and back in for the new actions to appear.
 
@@ -372,7 +372,7 @@ Which forms do you want to enable Voice to Form on?
 
 There are two ways to flip it. Pick based on what's available in the runtime.
 
-**Path A (preferred — agent-native browser MCP drive).** Verified working end-to-end: V2F triggered correctly on the mobile app after this path enabled the flag on real forms. The browser MCP is part of the agent runtime (like `execute_api`), not a shell or an external tool the skill depends on.
+**Path A (preferred — agent-native browser MCP drive).** Verified working end-to-end: V2F triggered correctly on the mobile app after this path enabled the flag on real forms. The browser MCP is part of the agent runtime (like `dispatch`), not a shell or an external tool the skill depends on.
 
 The sequence per form is exactly these clicks:
 1. Open Flow Builder on the form. Resolve the Flow Id for each selected form from the Step 5a list, then navigate the browser MCP to `<instanceUrl>/builder_platform_interaction/flowBuilder.app?flowId=<FLOW_ID>`. (The runtime supplies the authenticated session; the skill does not build `frontdoor.jsp` URLs or handle tokens.)
@@ -587,7 +587,7 @@ Run before declaring Voice to Form enabled in production:
 
 ## Conventions
 
-- **REST-native, no execution-environment dependency.** Every org read and write is a single `execute_api` REST call dispatched through the Codey runtime. The skill uses no `sf` CLI, no shell, no local Python or `jq`, no temp files, no metadata deploy, and no Apex. The one non-REST step (LLM Targetable) uses the agent-native browser MCP or a Setup deeplink — never a shell.
+- **REST-native, no execution-environment dependency.** Every org read and write is a single `dispatch` REST call dispatched through the Codey runtime. The skill uses no `sf` CLI, no shell, no local Python or `jq`, no temp files, no metadata deploy, and no Apex. The one non-REST step (LLM Targetable) uses the agent-native browser MCP or a Setup deeplink — never a shell.
 - **Idempotent.** Re-running on an already-configured org applies zero changes. LDS/permset/PSL writes are safe to re-run (204/no-op or `DUPLICATE_VALUE` treated as success).
 - **Read API names back from the org.** PSL DeveloperName, the permset Id, the form API-name list, and the FSM Settings row Id are all read live, never hard-coded.
 - **Trust the runtime probe over Tooling settings probes.** `Ai4mSettings.enableEinsteinGPT` returns `<missing>` even on fully-enabled orgs. The only honest check is the live LLM call in Step 1.5a.