@salesforce/afv-skills 1.3.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/afv-skills",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Salesforce skills for Agentforce Vibes",
   "license": "CC-BY-NC-4.0",
   "files": [
@@ -11,8 +11,8 @@
     "registry": "https://registry.npmjs.org"
   },
   "devDependencies": {
-    "@salesforce/webapp-template-app-react-sample-b2e-experimental": "1.109.1",
-    "@salesforce/webapp-template-app-react-sample-b2x-experimental": "1.109.1",
+    "@salesforce/webapp-template-app-react-sample-b2e-experimental": "^1.112.5",
+    "@salesforce/webapp-template-app-react-sample-b2x-experimental": "^1.112.5",
     "tsx": "^4.21.0"
   },
   "scripts": {

package/skills/building-webapp-data-visualization/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: building-webapp-data-visualization
-description: Adds data visualization components (charts, stat cards, KPI metrics) to React pages using Recharts. Use when the user asks to add a chart, graph, donut chart, pie chart, bar chart, stat card, KPI metric, dashboard visualization, or analytics component to the web application.
+description: "Adds data visualization components (charts, stat cards, KPI metrics) to React pages using Recharts. Use when the user asks to add a chart, graph, donut chart, pie chart, bar chart, stat card, KPI metric, dashboard visualization, or analytics component to the web application."
 ---
 
 # Data Visualization

package/skills/building-webapp-react-components/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: building-webapp-react-components
-description: Use when editing any React code in the web application — creating or modifying components, pages, layout, headers, footers, or any TSX/JSX files. Follow this skill for add component, add page, header/footer, and general React UI implementation patterns (shadcn UI and Tailwind CSS).
+description: "Use when editing any React code in the web application — creating or modifying components, pages, layout, headers, footers, or any TSX/JSX files. Follow this skill for add component, add page, header/footer, and general React UI implementation patterns (shadcn UI and Tailwind CSS)."
 ---
 
 # React Web App (Components, Pages, Layout)

package/skills/configuring-webapp-csp-trusted-sites/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: configuring-webapp-csp-trusted-sites
-description: Creates Salesforce CSP Trusted Site metadata when adding external domains. Use when the user adds an external API, CDN, image host, font provider, map tile server, or any third-party URL that the web application needs to load resources from — or when a browser console shows a CSP violation error.
+description: "Creates Salesforce CSP Trusted Site metadata when adding external domains. Use when the user adds an external API, CDN, image host, font provider, map tile server, or any third-party URL that the web application needs to load resources from — or when a browser console shows a CSP violation error."
 ---
 
 # CSP Trusted Sites

package/skills/configuring-webapp-metadata/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: configuring-webapp-metadata
-description: Use this skill when configuring web application metadata structure, webapplication.json, or bundle organization. Covers WebApplication bundle layout, meta XML, build output directory, and webapplication.json settings.
+description: "Use this skill when configuring web application metadata structure, webapplication.json, or bundle organization. Covers WebApplication bundle layout, meta XML, build output directory, and webapplication.json settings."
 ---
 
 # WebApplication Requirements
@@ -53,7 +53,7 @@ Applies to:
 
 Reject:
 - backslashes
-- leading `\`
+- leading `/` or `\`
 - `..` segments
 - null or control characters
 - globs: `*`, `?`, `**`

package/skills/creating-webapp/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: creating-webapp
-description: Use this skill when creating or setting up a new SFDX React web application. Covers first steps, npm install, skills-first protocol, deployment order, and core web app rules.
+description: "Use this skill when creating or setting up a new SFDX React web application. Covers first steps, npm install, skills-first protocol, deployment order, and core web app rules."
 paths:
   - "**/webapplications/**/*"
 ---
@@ -111,7 +111,7 @@ Apps run behind dynamic base paths. Router navigation (`<Link to>`, `navigate()`
 
 ## Module Restrictions
 
-React apps must NOT import Salesforce platform modules like `lightning/*` or `@wire` (LWC-only). For data access, invoke the **accessing-data** skill.
+React apps must NOT import Salesforce platform modules like `lightning/*` or `@wire` (LWC-only). For data access, invoke the **using-salesforce-data** skill.
 
 # Frontend Aesthetics
 
@@ -138,4 +138,3 @@ Only stop when:
 - All checklist items are completed and quality gates pass, or
 - A blocking error cannot be resolved after reasonable remediation, or
 - The user explicitly asks to pause.
-

package/skills/deploying-webapp-to-salesforce/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: deploying-webapp-to-salesforce
-description: Enforces the correct order for deploying metadata, assigning permission sets, and fetching GraphQL schema. Use for ANY deployment to a Salesforce org — webapps, LWC, Aura, Apex, metadata, schema fetch, or org sync. Codifies setup-cli.mjs.
-paths:
-  - "**/*"
+description: "Enforces the correct order for deploying metadata, assigning permission sets, and fetching GraphQL schema. Use for ANY deployment to a Salesforce org — webapps, LWC, Aura, Apex, metadata, schema fetch, or org sync. Codifies setup-cli.mjs."
 ---
 
 # Deploying to Salesforce
@@ -225,5 +223,4 @@ The project includes `scripts/setup-cli.mjs` which runs this sequence in batch.
 
 ## Related Skills
 
-- **exploring-graphql-schema** — Schema exploration (grep-only) after schema exists
-- **using-graphql** — Full GraphQL workflow (explore, query, codegen, lint)
+- **using-salesforce-data** — Full data access workflow (GraphQL queries/mutations, REST APIs, schema exploration, webapp integration)

package/skills/generating-custom-application/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generating-custom-application
-description: Use this skill when users need to create or configure Salesforce Custom Applications. Trigger when users mention custom apps, application metadata, app navigation, or organizing tabs into applications. Use when users want to create app containers for tabs and pages. Always use this skill for custom application work.
+description: "Use this skill when users need to create or configure Salesforce Custom Applications. Trigger when users mention custom apps, application metadata, app navigation, or organizing tabs into applications. Use when users want to create app containers for tabs and pages. Always use this skill for custom application work."
 ---
 
 ## When to Use This Skill

package/skills/generating-custom-field/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generating-custom-field
-description: Use this skill when users need to create, generate, or validate Salesforce Custom Field metadata. Trigger when users mention custom fields, field types, Roll-up Summary fields, Master-Detail relationships, Lookup relationships, formula fields, picklists, or field metadata. Also use when users encounter field deployment errors, especially around Roll-up Summary format, Master-Detail constraints, or formula issues. Always use this skill for any custom field metadata work, field generation, or field troubleshooting.
+description: "Use this skill when users need to create, generate, or validate Salesforce Custom Field metadata. Trigger when users mention custom fields, field types, Roll-up Summary fields, Master-Detail relationships, Lookup relationships, formula fields, picklists, or field metadata. Also use when users encounter field deployment errors, especially around Roll-up Summary format, Master-Detail constraints, or formula issues. Always use this skill for any custom field metadata work, field generation, or field troubleshooting."
 ---
 
 ## When to Use This Skill

package/skills/generating-custom-lightning-type/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generating-custom-lightning-type
-description: Use this skill when users need to create Custom Lightning Types (CLTs) for Einstein Agent actions or structured input/output schemas. Trigger when users mention CLT, Custom Lightning Types, JSON schemas for agents, type definitions, lightning__objectType, or editor/renderer configurations. This is complex - always use this skill for CLT work.
+description: "Use this skill when users need to create Custom Lightning Types (CLTs) for Einstein Agent actions or structured input/output schemas. Trigger when users mention CLT, Custom Lightning Types, JSON schemas for agents, type definitions, lightning__objectType, or editor/renderer configurations. This is complex - always use this skill for CLT work."
 ---
 
 ## When to Use This Skill

package/skills/generating-custom-object/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generating-custom-object
-description: Use this skill when users need to create, generate, or validate Salesforce Custom Object metadata. Trigger when users mention custom objects, creating objects, object metadata, .object files, sharing models, name fields, or validation rules on objects. Also use when users say things like "create a custom object", "generate object metadata", "set up an object for...", or when they're troubleshooting object deployment errors especially around sharing models and Master-Detail relationships. Always use this skill for any custom object metadata work.
+description: "Use this skill when users need to create, generate, or validate Salesforce Custom Object metadata. Trigger when users mention custom objects, creating objects, object metadata, .object files, sharing models, name fields, or validation rules on objects. Also use when users say things like \"create a custom object\", \"generate object metadata\", \"set up an object for...\", or when they're troubleshooting object deployment errors especially around sharing models and Master-Detail relationships. Always use this skill for any custom object metadata work."
 ---
 
 ## When to Use This Skill

package/skills/generating-custom-tab/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generating-custom-tab
-description: Use this skill when users need to create or configure Salesforce Custom Tabs. Trigger when users mention tabs, navigation tabs, object tabs, web tabs, Visualforce tabs, Lightning component tabs, app page tabs, or tab configuration. Also use when users want to add navigation to custom objects, create tabs for external content, or set up Lightning page tabs. Always use this skill for any custom tab work.
+description: "Use this skill when users need to create or configure Salesforce Custom Tabs. Trigger when users mention tabs, navigation tabs, object tabs, web tabs, Visualforce tabs, Lightning component tabs, app page tabs, or tab configuration. Also use when users want to add navigation to custom objects, create tabs for external content, or set up Lightning page tabs. Always use this skill for any custom tab work."
 ---
 
 ## When to Use This Skill

package/skills/generating-experience-lwr-site/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generating-experience-lwr-site
-description: Creates, modifies, or manages Salesforce Experience Cloud LWR sites via DigitalExperience metadata. Always trigger when users mention Experience sites, LWR sites, DigitalExperience, Experience Cloud, community sites, portals, creating pages, adding routes, views, theme layouts, branding sets, previewing sites, or any DigitalExperience bundle work. Also use when users mention specific content types like sfdc_cms__route, sfdc_cms__themeLayout, etc. or when troubleshooting site deployment.
+description: "Creates, modifies, or manages Salesforce Experience Cloud LWR sites via DigitalExperience metadata. Always trigger when users mention Experience sites, LWR sites, DigitalExperience, Experience Cloud, community sites, portals, creating pages, adding routes, views, theme layouts, branding sets, previewing sites, or any DigitalExperience bundle work. Also use when users mention specific content types like sfdc_cms__route, sfdc_cms__themeLayout, etc. or when troubleshooting site deployment."
 ---
 
 # Experience LWR Site Builder

package/skills/generating-experience-react-site/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generating-experience-react-site
-description: Use this skill when users need to create or configure a Salesforce Digital Experience Site specifically for hosting a React web application. Trigger when users mention creating an Experience site for a React app, setting up a React site on Salesforce, configuring Network/CustomSite/DigitalExperience metadata for a web app, or deploying site infrastructure for a React application. Also trigger when users mention site URL path prefixes, app namespaces, appDevName, guest access configuration, DigitalExperienceConfig, DigitalExperienceBundle, or sfdc_cms__site content types in the context of React apps. Always use this skill for any React web application site creation or site infrastructure configuration work, even if the user just says "create a site for my React app" or "set up the site for my web application."
+description: "Use this skill when users need to create or configure a Salesforce Digital Experience Site specifically for hosting a React web application. Trigger when users mention creating an Experience site for a React app, setting up a React site on Salesforce, configuring Network/CustomSite/DigitalExperience metadata for a web app, or deploying site infrastructure for a React application. Also trigger when users mention site URL path prefixes, app namespaces, appDevName, guest access configuration, DigitalExperienceConfig, DigitalExperienceBundle, or sfdc_cms__site content types in the context of React apps. Always use this skill for any React web application site creation or site infrastructure configuration work, even if the user just says \"create a site for my React app\" or \"set up the site for my web application.\""
 ---
 
 # Digital Experience Site for React Web Applications

package/skills/generating-flexipage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generating-flexipage
-description: Use this skill when users need to create, generate, modify, or validate Salesforce Lightning pages (FlexiPages). Trigger when users mention RecordPage, AppPage, HomePage, Lightning pages, page layouts, adding components to pages, or page customization. Also use when users say things like "create a Lightning page", "add a component to a page", "customize the record page", "generate a FlexiPage", or when they're working with FlexiPage XML files and need help with components, regions, or deployment errors. Always use this skill for any FlexiPage-related work, even if they just mention "page" in the context of Salesforce.
+description: "Use this skill when users need to create, generate, modify, or validate Salesforce Lightning pages (FlexiPages). Trigger when users mention RecordPage, AppPage, HomePage, Lightning pages, page layouts, adding components to pages, or page customization. Also use when users say things like \"create a Lightning page\", \"add a component to a page\", \"customize the record page\", \"generate a FlexiPage\", or when they're working with FlexiPage XML files and need help with components, regions, or deployment errors. Always use this skill for any FlexiPage-related work, even if they just mention \"page\" in the context of Salesforce."
 ---
 
 ## When to Use This Skill

package/skills/generating-flow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generating-flow
-description: Generate Salesforce Flows using the MCP tool execute_metadata_action. Use when the user asks to create, build, or generate a flow — including Screen, Autolaunched, Record-Triggered (before/after-save), Scheduled. Also trigger for flow-like requests such as "when a record is created", "trigger daily at", "send an email when", "update the field when", "automate", "workflow", or "flow XML/metadata". This is the only skill for Salesforce Flow generation.
+description: "Generate Salesforce Flows using the MCP tool execute_metadata_action. Use when the user asks to create, build, or generate a flow — including Screen, Autolaunched, Record-Triggered (before/after-save), Scheduled. Also trigger for flow-like requests such as \"when a record is created\", \"trigger daily at\", \"send an email when\", \"update the field when\", \"automate\", \"workflow\", or \"flow XML/metadata\". This is the only skill for Salesforce Flow generation."
 ---
 
 ## Goal

package/skills/generating-fragment/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generating-fragment
-description: Use this skill when users need to create or edit Salesforce Fragments (reusable UI pieces). Trigger when users mention fragments, UEM blocks, reusable UI templates, structured rendering across Slack/Mobile/LEX, or block-based layouts. Also use when users want to create unified experience components. Always use this skill for any fragment work.
+description: "Use this skill when users need to create or edit Salesforce Fragments (reusable UI pieces). Trigger when users mention fragments, UEM blocks, reusable UI templates, structured rendering across Slack/Mobile/LEX, or block-based layouts. Also use when users want to create unified experience components. Always use this skill for any fragment work."
 ---
 
 ## When to Use This Skill

package/skills/generating-list-view/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generating-list-view
-description: Use this skill when users need to create, generate, or validate Salesforce List View metadata. Trigger when users mention list views, filtered record lists, creating views, setting up record columns, filtering records by criteria, or ask about list view visibility. Also use when users say things like "I need a view that shows...", "filter records by...", "create a list view for...", or when they're working with ListView XML files and need validation or troubleshooting.
+description: "Use this skill when users need to create, generate, or validate Salesforce List View metadata. Trigger when users mention list views, filtered record lists, creating views, setting up record columns, filtering records by criteria, or ask about list view visibility. Also use when users say things like \"I need a view that shows...\", \"filter records by...\", \"create a list view for...\", or when they're working with ListView XML files and need validation or troubleshooting."
 ---
 
 ## When to Use This Skill

package/skills/generating-permission-set/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generating-permission-set
-description: Generates correct, deployable Salesforce permission set metadata (PermissionSet XML) with object, field, user, and app permissions. Use this skill when creating or editing permission set metadata, object permissions, field-level security (FLS), tab visibility, or deploying permission sets.
+description: "Generates correct, deployable Salesforce permission set metadata (PermissionSet XML) with object, field, user, and app permissions. Use this skill when creating or editing permission set metadata, object permissions, field-level security (FLS), tab visibility, or deploying permission sets."
 compatibility: Salesforce Metadata API v60.0+
 metadata:
   author: afv-library

package/skills/generating-validation-rule/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generating-validation-rule
-description: Use this skill when users need to create, modify, or validate Salesforce Validation Rules. Trigger when users mention validation rules, field validation, data quality rules, formula validation, error messages, or validation logic. Also use when users encounter validation errors, need to update formulas, or want to enforce business rules at the data layer. Always use this skill for any validation rule work.
+description: "Use this skill when users need to create, modify, or validate Salesforce Validation Rules. Trigger when users mention validation rules, field validation, data quality rules, formula validation, error messages, or validation logic. Also use when users encounter validation errors, need to update formulas, or want to enforce business rules at the data layer. Always use this skill for any validation rule work."
 ---
 
 ## When to Use This Skill

package/skills/implementing-webapp-file-upload/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: implementing-webapp-file-upload
-description: Add file upload functionality to React webapps with progress tracking and Salesforce ContentVersion integration. Use when the user wants to upload files, attach documents, handle file input, create file dropzones, track upload progress, or link files to Salesforce records. This feature provides programmatic APIs ONLY — no components or hooks are exported. Build your own custom UI using the upload() API. ALWAYS use this feature instead of building file upload from scratch with FormData or XHR.
+description: "Add file upload functionality to React webapps with progress tracking and Salesforce ContentVersion integration. Use when the user wants to upload files, attach documents, handle file input, create file dropzones, track upload progress, or link files to Salesforce records. This feature provides programmatic APIs ONLY — no components or hooks are exported. Build your own custom UI using the upload() API. ALWAYS use this feature instead of building file upload from scratch with FormData or XHR."
 ---
 
 # File Upload API (workflow)

package/skills/installing-webapp-features/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: installing-webapp-features
-description: Search, describe, and install pre-built UI features (authentication, shadcn components, navigation, search, GraphQL, Agentforce AI) into Salesforce webapps. Use this when the user wants to add functionality to a webapp, or when determining what salesforce-provided features are available — whether prompted by the user or on your own initiative. Always check for an existing feature before building from scratch.
+description: "Search, describe, and install pre-built UI features (authentication, shadcn components, navigation, search, GraphQL, Agentforce AI) into Salesforce webapps. Use this when the user wants to add functionality to a webapp, or when determining what salesforce-provided features are available — whether prompted by the user or on your own initiative. Always check for an existing feature before building from scratch."
 ---
 
 # webapps-features-experimental CLI — Agent Reference

package/skills/managing-webapp-agentforce-conversation-client/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: managing-webapp-agentforce-conversation-client
-description: Adds or modifies AgentforceConversationClient in React apps (.tsx or .jsx files). Use when user says "add chat widget", "embed agentforce", "add agent", "add chatbot", "integrate conversational AI", or asks to change colors, dimensions, styling, or configure agentId, width, height, inline mode, or styleTokens for travel agent, HR agent, employee agent, or any Salesforce agent chat.
+description: "Adds or modifies AgentforceConversationClient in React apps (.tsx or .jsx files). Use when user says \"add chat widget\", \"embed agentforce\", \"add agent\", \"add chatbot\", \"integrate conversational AI\", or asks to change colors, dimensions, styling, or configure agentId, width, height, inline mode, or styleTokens for travel agent, HR agent, employee agent, or any Salesforce agent chat."
 metadata:
   author: ACC Components
   version: 1.0.0

package/skills/trigger-refactor-pipeline/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: trigger-refactor-pipeline
-description: Refactor Salesforce triggers into handler patterns with automated test generation and deployment. Use when modernizing legacy triggers with DML/SOQL in loops or inconsistent patterns.
+description: "Refactor Salesforce triggers into handler patterns with automated test generation and deployment. Use when modernizing legacy triggers with DML/SOQL in loops or inconsistent patterns."
 license: Apache-2.0
 compatibility: Requires Salesforce CLI, Python 3.9+
 metadata:

package/skills/using-webapp-salesforce-data/SKILL.md

@@ -0,0 +1,363 @@
+---
+name: using-webapp-salesforce-data
+description: "Salesforce data access for reading, writing, and querying records via REST, GraphQL, Apex, or Platform SDK. Use when the user wants to fetch, search, filter, sort, display, create, update, delete, or attach files to Salesforce records (standard objects like Accounts, Contacts, Opportunities, Cases, Quotes, or any custom object) in a web app or UI component (React, Angular, Vue, etc.); call Chatter, Connect, or Apex REST APIs; or invoke AuraEnabled Apex methods from an external app. Does not apply to authentication/OAuth setup, schema changes (adding fields, relationships), Bulk/Tooling/Metadata API usage, declarative automation (Flows, Process Builder), general LWC/Apex coding guidance without a specific data operation, or Salesforce admin/configuration tasks."
+---
+
+# Salesforce Data Access
+
+## When to Use
+
+Use this skill when the user wants to:
+
+- **Fetch or display Salesforce data** — Query records (Account, Contact, Opportunity, custom objects) to show in a component
+- **Create, update, or delete records** — Perform mutations on Salesforce data
+- **Add data fetching to a component** — Wire up a React component to Salesforce data
+- **Call REST APIs** — Use Connect REST, Apex REST, or UI API endpoints
+- **Explore the org schema** — Discover available objects, fields, or relationships
+
+## Data SDK Requirement
+
+> **All Salesforce data access MUST use the Data SDK** (`@salesforce/sdk-data`). The SDK handles authentication, CSRF, and base URL resolution. Never use `fetch()` or `axios` directly.
+
+```typescript
+import { createDataSDK, gql } from "@salesforce/sdk-data";
+
+const sdk = await createDataSDK();
+
+// GraphQL for record queries/mutations (PREFERRED)
+const response = await sdk.graphql?.<ResponseType>(query, variables);
+
+// REST for Connect REST, Apex REST, UI API (when GraphQL insufficient)
+const res = await sdk.fetch?.("/services/apexrest/my-resource");
+```
+
+**Always use optional chaining** (`sdk.graphql?.()`, `sdk.fetch?.()`) — these methods may be undefined in some surfaces.
+
+## Supported APIs
+
+**Only the following APIs are permitted.** Any endpoint not listed here must not be used.
+
+| API | Method | Endpoints / Use Case |
+|-----|--------|----------------------|
+| GraphQL | `sdk.graphql` | All record queries and mutations via `uiapi { }` namespace |
+| UI API REST | `sdk.fetch` | `/services/data/v{ver}/ui-api/records/{id}` — record metadata when GraphQL is insufficient |
+| Apex REST | `sdk.fetch` | `/services/apexrest/{resource}` — custom server-side logic, aggregates, multi-step transactions |
+| Connect REST | `sdk.fetch` | `/services/data/v{ver}/connect/file/upload/config` — file upload config |
+| Einstein LLM | `sdk.fetch` | `/services/data/v{ver}/einstein/llm/prompt/generations` — AI text generation |
+
+**Not supported:**
+
+- **Enterprise REST query endpoint** (`/services/data/v*/query` with SOQL) — blocked at the proxy level. Use GraphQL for record reads; use Apex REST if server-side SOQL aggregates are required.
+- **Aura-enabled Apex** (`@AuraEnabled`) — an LWC/Aura pattern with no invocation path from React webapps.
+- **Chatter API** (`/chatter/users/me`) — use `uiapi { currentUser { ... } }` in a GraphQL query instead.
+- **Any other Salesforce REST endpoint** not listed in the supported table above.
+
+## Decision: GraphQL vs REST
+
+| Need | Method | Example |
+|------|--------|---------|
+| Query/mutate records | `sdk.graphql` | Account, Contact, custom objects |
+| Current user info | `sdk.graphql` | `uiapi { currentUser { Id Name { value } } }` |
+| UI API record metadata | `sdk.fetch` | `/ui-api/records/{id}` |
+| Connect REST | `sdk.fetch` | `/connect/file/upload/config` |
+| Apex REST | `sdk.fetch` | `/services/apexrest/auth/login` |
+| Einstein LLM | `sdk.fetch` | `/einstein/llm/prompt/generations` |
+
+**GraphQL is preferred** for record operations. Use REST only when GraphQL doesn't cover the use case.
+
+---
+
+## GraphQL Workflow
+
+### Step 1: Acquire Schema
+
+The `schema.graphql` file (265K+ lines) is the source of truth. **Never open or parse it directly.**
+
+1. Check if `schema.graphql` exists at the SFDX project root
+2. If missing, run from the **webapp dir**: `npm run graphql:schema`
+3. Custom objects appear only after metadata is deployed
+
+### Step 2: Look Up Entity Schema
+
+Map user intent to PascalCase names ("accounts" → `Account`), then **run the search script from the project root**:
+
+```bash
+# From project root — look up all relevant schema info for one or more entities
+bash .a4drules/skills/using-salesforce-data/graphql-search.sh Account
+
+# Multiple entities at once
+bash .a4drules/skills/using-salesforce-data/graphql-search.sh Account Contact Opportunity
+```
+
+The script outputs five sections per entity:
+1. **Type definition** — all queryable fields and relationships
+2. **Filter options** — available fields for `where:` conditions
+3. **Sort options** — available fields for `orderBy:`
+4. **Create input** — fields accepted by create mutations
+5. **Update input** — fields accepted by update mutations
+
+Use this output to determine exact field names before writing any query or mutation. **Maximum 2 script runs.** If the entity still can't be found, ask the user — the object may not be deployed.
+
+### Step 3: Generate Query
+
+Use the templates below. Every field name **must** be verified from the script output in Step 2.
+
+#### Read Query Template
+
+```graphql
+query GetAccounts {
+  uiapi {
+    query {
+      Account(where: { Industry: { eq: "Technology" } }, first: 10) {
+        edges {
+          node {
+            Id
+            Name @optional { value }
+            Industry @optional { value }
+            # Parent relationship
+            Owner @optional { Name { value } }
+            # Child relationship
+            Contacts @optional {
+              edges { node { Name @optional { value } } }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**FLS Resilience**: Apply `@optional` to all record fields. The server omits inaccessible fields instead of failing. Consuming code must use optional chaining:
+
+```typescript
+const name = node.Name?.value ?? "";
+```
+
+#### Mutation Template
+
+```graphql
+mutation CreateAccount($input: AccountCreateInput!) {
+  uiapi {
+    AccountCreate(input: $input) {
+      Record { Id Name { value } }
+    }
+  }
+}
+```
+
+**Mutation constraints:**
+- Create: Include required fields, only `createable` fields, no child relationships
+- Update: Include `Id`, only `updateable` fields
+- Delete: Include `Id` only
+
+#### Object Metadata & Picklist Values
+
+Use `uiapi { objectInfos(...) }` to fetch field metadata or picklist values. Pass **either** `apiNames` or `objectInfoInputs` — never both in the same query.
+
+**Object metadata** (field labels, data types, CRUD flags):
+
+```typescript
+const GET_OBJECT_INFO = gql`
+  query GetObjectInfo($apiNames: [String!]!) {
+    uiapi {
+      objectInfos(apiNames: $apiNames) {
+        ApiName
+        label
+        labelPlural
+        fields {
+          ApiName
+          label
+          dataType
+          updateable
+          createable
+        }
+      }
+    }
+  }
+`;
+
+const sdk = await createDataSDK();
+const response = await sdk.graphql?.(GET_OBJECT_INFO, { apiNames: ["Account"] });
+const objectInfos = response?.data?.uiapi?.objectInfos ?? [];
+```
+
+**Picklist values** (use `objectInfoInputs` + `... on PicklistField` inline fragment):
+
+```typescript
+const GET_PICKLIST_VALUES = gql`
+  query GetPicklistValues($objectInfoInputs: [ObjectInfoInput!]!) {
+    uiapi {
+      objectInfos(objectInfoInputs: $objectInfoInputs) {
+        ApiName
+        fields {
+          ApiName
+          ... on PicklistField {
+            picklistValuesByRecordTypeIDs {
+              recordTypeID
+              picklistValues {
+                label
+                value
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+`;
+
+const response = await sdk.graphql?.(GET_PICKLIST_VALUES, {
+  objectInfoInputs: [{ objectApiName: "Account" }],
+});
+const fields = response?.data?.uiapi?.objectInfos?.[0]?.fields ?? [];
+```
+
+### Step 4: Validate & Test
+
+1. **Lint**: `npx eslint <file>` from webapp dir
+2. **Test**: Ask user before testing. For mutations, request input values — never fabricate data.
+
+**If ESLint reports a GraphQL error** (e.g. `Cannot query field`, `Unknown type`, `Unknown argument`), the field or type name is wrong. Re-run the schema search script to find the correct name — do not guess:
+
+```bash
+# From project root — re-check the entity that caused the error
+bash .a4drules/skills/using-salesforce-data/graphql-search.sh <EntityName>
+```
+
+Then fix the query using the exact names from the script output.
+
+---
+
+## Webapp Integration (React)
+
+```typescript
+import { createDataSDK, gql } from "@salesforce/sdk-data";
+
+const GET_ACCOUNTS = gql`
+  query GetAccounts {
+    uiapi {
+      query {
+        Account(first: 10) {
+          edges {
+            node {
+              Id
+              Name @optional { value }
+              Industry @optional { value }
+            }
+          }
+        }
+      }
+    }
+  }
+`;
+
+const sdk = await createDataSDK();
+const response = await sdk.graphql?.(GET_ACCOUNTS);
+
+if (response?.errors?.length) {
+  throw new Error(response.errors.map(e => e.message).join("; "));
+}
+
+const accounts = response?.data?.uiapi?.query?.Account?.edges?.map(e => e.node) ?? [];
+```
+
+---
+
+## REST API Patterns
+
+Use `sdk.fetch` when GraphQL is insufficient. See the [Supported APIs](#supported-apis) table for the full allowlist.
+
+```typescript
+declare const __SF_API_VERSION__: string;
+const API_VERSION = typeof __SF_API_VERSION__ !== "undefined" ? __SF_API_VERSION__ : "65.0";
+
+// Connect — file upload config
+const res = await sdk.fetch?.(`/services/data/v${API_VERSION}/connect/file/upload/config`);
+
+// Apex REST (no version in path)
+const res = await sdk.fetch?.("/services/apexrest/auth/login", {
+  method: "POST",
+  body: JSON.stringify({ email, password }),
+  headers: { "Content-Type": "application/json" },
+});
+
+// UI API — record with metadata (prefer GraphQL for simple reads)
+const res = await sdk.fetch?.(`/services/data/v${API_VERSION}/ui-api/records/${recordId}`);
+
+// Einstein LLM
+const res = await sdk.fetch?.(`/services/data/v${API_VERSION}/einstein/llm/prompt/generations`, {
+  method: "POST",
+  body: JSON.stringify({ promptTextorId: prompt }),
+});
+```
+
+**Current user**: Do not use Chatter (`/chatter/users/me`). Use GraphQL instead:
+
+```typescript
+const GET_CURRENT_USER = gql`
+  query CurrentUser {
+    uiapi { currentUser { Id Name { value } } }
+  }
+`;
+const response = await sdk.graphql?.(GET_CURRENT_USER);
+```
+
+---
+
+## Directory Structure
+
+```
+<project-root>/                              ← SFDX project root
+├── schema.graphql                           ← grep target (lives here)
+├── sfdx-project.json
+└── force-app/main/default/webapplications/<app-name>/  ← webapp dir
+    ├── package.json                         ← npm scripts
+    └── src/
+```
+
+| Command | Run From | Why |
+|---------|----------|-----|
+| `npm run graphql:schema` | webapp dir | Script in webapp's package.json |
+| `npx eslint <file>` | webapp dir | Reads eslint.config.js |
+| `bash .a4drules/skills/using-salesforce-data/graphql-search.sh <Entity>` | project root | Schema lookup |
+| `sf api request rest` | project root | Needs sfdx-project.json |
+
+---
+
+## Quick Reference
+
+### Schema Lookup (from project root)
+
+Run the search script to get all relevant schema info in one step:
+
+```bash
+bash .a4drules/skills/using-salesforce-data/graphql-search.sh <EntityName>
+```
+
+| Script Output Section | Used For |
+|-----------------------|----------|
+| Type definition | Field names, parent/child relationships |
+| Filter options | `where:` conditions |
+| Sort options | `orderBy:` |
+| CreateRepresentation | Create mutation field list |
+| UpdateRepresentation | Update mutation field list |
+
+### Error Categories
+
+| Error Contains | Resolution |
+|----------------|------------|
+| `Cannot query field` | Field name is wrong — run `graphql-search.sh <Entity>` and use the exact name from the Type definition section |
+| `Unknown type` | Type name is wrong — run `graphql-search.sh <Entity>` to confirm the correct PascalCase entity name |
+| `Unknown argument` | Argument name is wrong — run `graphql-search.sh <Entity>` and check Filter or OrderBy sections |
+| `invalid syntax` | Fix syntax per error message |
+| `validation error` | Field name is wrong — run `graphql-search.sh <Entity>` to verify |
+| `VariableTypeMismatch` | Correct argument type from schema |
+| `invalid cross reference id` | Entity deleted — ask for valid Id |
+
+### Checklist
+
+- [ ] All field names verified via search script (Step 2)
+- [ ] `@optional` applied to record fields (reads)
+- [ ] Optional chaining in consuming code
+- [ ] Lint passes: `npx eslint <file>`