@salesforce/afv-skills 1.65.0 → 1.66.0

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

@@ -1,31 +1,52 @@
 ---
 name: field-service-sobject-create-configure
-description: "Headless 360 REST API deployment step for creating sObject records. Handles describe-based field discovery, required field derivation, entity relationship ordering, and composite graph transactions. Called by designer skills after design confirmation; can also be used directly for non-setup sObject creation."
+description: "Headless 360 REST API deployment step for creating sObject records. Handles describe-based field discovery, required-field derivation, entity-relationship ordering, and composite graph transactions. Use this skill when a designer skill (or a user directly) needs to create sObject records after design confirmation, including non-setup sObject creation."
+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
@@ -53,11 +74,22 @@ to see conventions and dupes. Then create with the derived body, e.g.
   "body": { "Name": "Standard Repair", "EstimatedDuration": 2 } }
 ```
 
-<!-- skill-validate: ignore-start -->
-<!-- codey:operations start -->
+─────
+**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 this skill uses — routing and dependency reference.
+Operations grouped by purpose. Use these as the building blocks for the workflows above.
+
+### Summary
 
 | Operation | Purpose | Status | Call | Depends on |
 |-----------|---------|--------|------|------------|
@@ -67,5 +99,173 @@ Operations this skill uses — routing and dependency reference.
 | `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}` | — |
-<!-- codey:operations end -->
-<!-- skill-validate: ignore-end -->
+
+### 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

@@ -1,12 +1,13 @@
 ---
 name: field-service-voice-to-form-configure
-description: "Set up Voice to Form on Field Service Mobile end-to-end against a Salesforce org. Covers BOTH variants in a single skill: Voice to Record Edit (voice-fills any record edit screen) and Voice to Form Data Capture (voice-fills Discovery Framework / Data Capture forms). For Data Capture, the skill is interactive: it discovers existing DC forms in the org and asks the admin which to enable. If no DC forms exist, it hands off to the fs-data-capture-form-deployer skill in this repo to create them, then resumes. Also assigns every permission a Field Service mobile user needs to actually use voice on-device, and walks the admin through the Einstein generative AI base setup wizard which is the most common reason voice 'works' but returns 'we couldn't recommend any updates'. TRIGGER when: user asks to enable, configure, install, or set up Voice to Form, V2F, Voice to Record Edit, V2RE, the microphone on the mobile app, or voice-fill on Field Service Mobile; user asks to turn on voice for Data Capture forms or for record edit. DO NOT TRIGGER when: user wants Pre-Work Brief (use setting-up-pre-work-brief); user wants to author a brand new Data Capture form (use fs-data-capture-form-deployer); user wants to build a generic Agentforce agent (use developing-agentforce)."
+description: "Set up Voice to Form on Field Service Mobile end-to-end against a Salesforce org, covering both variants: Voice to Record Edit (voice-fills any record-edit screen) and Voice to Form Data Capture (voice-fills Discovery Framework / Data Capture forms). Discovers existing DC forms and asks which to enable, hands off to fs-data-capture-form-deployer to create them if none exist, assigns every permission a mobile user needs, and walks the admin through the Einstein generative AI base setup. TRIGGER when the user asks to enable, configure, install, or set up Voice to Form, V2F, Voice to Record Edit, V2RE, the microphone on the mobile app, or voice-fill on Field Service Mobile. DO NOT TRIGGER when the user wants Pre-Work Brief, wants to author a brand-new Data Capture form, or wants to build a generic Agentforce agent."
+user-invocable: false
 metadata:
   version: "1.0"
+  domains: ["Field Service"]
   cliTools:
-  - tool:
-    - "sf"
-    semver: ">=2.0.0"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
 ---
 
 # Setting up Voice to Form
@@ -43,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.
@@ -195,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:
 
@@ -267,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.
 
@@ -647,33 +648,3 @@ External (Salesforce Help):
 - **Einstein LLM runtime entitlement.** Trial / SDO orgs commonly have all PSLs assigned but the runtime never turned on. Step 1.5 detects and surfaces this; resolution is a UI wizard click-through. SDO orgs occasionally need Salesforce-side enablement even after the wizard.
 - **LDS on stubborn templates.** On rare SDO/trial templates the `enableLsdkMode` write reports success but doesn't flip; Step 1c re-reads to catch this and falls back to the Setup deeplink.
 - **Component-type coverage.** V2F doesn't support Upload Image, Upload File, Image Preview, Matrix, Lookup, or Signature components in DC forms. A form composed entirely of these shows no mic icon.
-
-<!-- skill-validate: ignore-start -->
-<!-- codey:operations start -->
-## Operations Reference
-
-Operations this skill uses — routing and dependency reference.
-
-| Operation | Purpose | Status | Call | Depends on |
-|-----------|---------|--------|------|------------|
-| `detect-psls` | read | — | `GET /services/data/v62.0/query` | — |
-| `detect-einstein-fs-permset` | read | — | `GET /services/data/v62.0/query` | `detect-psls` |
-| `detect-lds-mode` | read | — | `GET /services/data/v62.0/tooling/query` | — |
-| `detect-v2re-org-switch` | read | — | `GET /services/data/v62.0/query` | — |
-| `detect-dc-forms` | read | — | `GET /services/data/v62.0/tooling/query` | — |
-| `detect-v2f-permset-clone` | read | — | `GET /services/data/v62.0/query` | — |
-| `pick-technician-user` | read | — | `GET /services/data/v62.0/query` | `detect-dc-forms` |
-| `enable-lds-mode` | write | — | `PATCH /services/data/v62.0/tooling/sobjects/FieldServiceSettings/{Id}` | `detect-lds-mode` |
-| `probe-einstein-runtime` | verify | — | `GET /services/data/v62.0/einstein/prompt-templates` | `enable-lds-mode` |
-| `enable-v2re-org-switch` | write | — | `PATCH /services/data/v62.0/sobjects/FieldServiceMobileSettings/{Id}` | `detect-v2re-org-switch` |
-| `describe-permset-fields` | verify | — | `GET /services/data/v62.0/sobjects/PermissionSet/describe` | `detect-einstein-fs-permset` |
-| `create-v2f-permset` | write | — | `POST /services/data/v62.0/sobjects/PermissionSet` | `describe-permset-fields` |
-| `verify-v2f-permset-deployed` | verify | — | `GET /services/data/v62.0/query` | `create-v2f-permset` |
-| `list-active-dc-forms` | read | — | `GET /services/data/v62.0/tooling/query` | `verify-v2f-permset-deployed` |
-| `enable-llm-targetable-on-forms` | write | — | — | `list-active-dc-forms` |
-| `assign-psls-to-user` | write | — | `POST /services/data/v62.0/sobjects/PermissionSetLicenseAssign` | `enable-llm-targetable-on-forms` |
-| `assign-cloned-permset` | write | — | `POST /services/data/v62.0/sobjects/PermissionSetAssignment` | `assign-psls-to-user` |
-| `verify-mobile-user-stack` | verify | — | `GET /services/data/v62.0/query` | `assign-cloned-permset` |
-| `handoff-to-deployer-when-no-forms` | write | — | → `sfs-mobile-core-experience/fs-data-capture-form-deployer` | — |
-<!-- codey:operations end -->
-<!-- skill-validate: ignore-end -->