@salesforce/webapp-template-feature-react-global-search-experimental 1.112.2 → 1.112.4

package/dist/.a4drules/skills/deploying-to-salesforce/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: deploying-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:
-  - "**/*"
 ---
 
 # Deploying to Salesforce

package/dist/.a4drules/skills/using-salesforce-data/SKILL.md

@@ -1,10 +1,6 @@
 ---
 name: using-salesforce-data
-description: Salesforce data access for reads, mutations, and REST APIs. Use when the user wants to fetch, display, create, update, or delete Salesforce records; add data fetching to a component; query Accounts, Contacts, Opportunities, or custom objects; call Chatter, Connect, or Apex REST APIs; or integrate Salesforce data into a webapp.
-paths:
-  - "**/*.ts"
-  - "**/*.tsx"
-  - "**/*.graphql"
+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
@@ -16,7 +12,7 @@ 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 Chatter, Connect, Apex REST, or UI API endpoints
+- **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
@@ -31,18 +27,38 @@ const sdk = await createDataSDK();
 // GraphQL for record queries/mutations (PREFERRED)
 const response = await sdk.graphql?.<ResponseType>(query, variables);
 
-// REST for Chatter, Connect, Apex REST (when GraphQL insufficient)
-const res = await sdk.fetch?.("/services/data/v65.0/chatter/users/me");
+// 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 |
-| Chatter API | `sdk.fetch` | `/chatter/users/me` |
+| 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` |
@@ -55,32 +71,36 @@ const res = await sdk.fetch?.("/services/data/v65.0/chatter/users/me");
 
 ### Step 1: Acquire Schema
 
-The `schema.graphql` file (265K+ lines) is the source of truth. **Use grep only** — never open or parse the file directly.
+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: Identify & Introspect Entities
+### Step 2: Look Up Entity Schema
 
-Map user intent to PascalCase names ("accounts" → `Account`). Validate via grep:
+Map user intent to PascalCase names ("accounts" → `Account`), then **run the search script from the project root**:
 
 ```bash
-# From project root — find entity fields
-grep -nE '^type Account implements Record' ./schema.graphql -A 100
+# From project root — look up all relevant schema info for one or more entities
+bash .a4drules/skills/using-salesforce-data/graphql-search.sh Account
 
-# Find filter options
-grep -nE '^input Account_Filter' ./schema.graphql -A 50
-
-# Find mutation input
-grep -nE '^input AccountCreateInput' ./schema.graphql -A 50
+# Multiple entities at once
+bash .a4drules/skills/using-salesforce-data/graphql-search.sh Account Contact Opportunity
 ```
 
-**Maximum 3 introspection cycles.** If entities remain unknown, ask the user.
+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 via grep.
+Use the templates below. Every field name **must** be verified from the script output in Step 2.
 
 #### Read Query Template
 
@@ -131,31 +151,109 @@ mutation CreateAccount($input: AccountCreateInput!) {
 - 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
-sf api request rest /services/data/v65.0/graphql \
-  --method POST \
-  --body '{"query":"..."}'
+# 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)
 
-### Pattern 1: External .graphql File (Recommended)
-
 ```typescript
-import { createDataSDK, type NodeOfConnection } from "@salesforce/sdk-data";
-import GET_ACCOUNTS from "./query/getAccounts.graphql?raw";
-import type { GetAccountsQuery } from "../graphql-operations-types";
+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?.<GetAccountsQuery>(GET_ACCOUNTS);
+const response = await sdk.graphql?.(GET_ACCOUNTS);
 
 if (response?.errors?.length) {
   throw new Error(response.errors.map(e => e.message).join("; "));
@@ -164,37 +262,16 @@ if (response?.errors?.length) {
 const accounts = response?.data?.uiapi?.query?.Account?.edges?.map(e => e.node) ?? [];
 ```
 
-After creating/modifying `.graphql` files, run: `npm run graphql:codegen`
-
-### Pattern 2: Inline gql Tag
-
-```typescript
-import { createDataSDK, gql } from "@salesforce/sdk-data";
-
-const GET_CURRENT_USER = gql`
-  query CurrentUser {
-    uiapi { currentUser { Id Name { value } } }
-  }
-`;
-
-const response = await sdk.graphql?.<CurrentUserQuery>(GET_CURRENT_USER);
-```
-
-**Must use `gql` tag** — plain template strings bypass ESLint validation.
-
 ---
 
 ## REST API Patterns
 
-Use `sdk.fetch` when GraphQL is insufficient:
+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";
 
-// Chatter — current user
-const res = await sdk.fetch?.(`/services/data/v${API_VERSION}/chatter/users/me`);
-
 // Connect — file upload config
 const res = await sdk.fetch?.(`/services/data/v${API_VERSION}/connect/file/upload/config`);
 
@@ -205,6 +282,9 @@ const res = await sdk.fetch?.("/services/apexrest/auth/login", {
   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",
@@ -212,6 +292,17 @@ const res = await sdk.fetch?.(`/services/data/v${API_VERSION}/einstein/llm/promp
 });
 ```
 
+**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
@@ -222,47 +313,51 @@ const res = await sdk.fetch?.(`/services/data/v${API_VERSION}/einstein/llm/promp
 ├── sfdx-project.json
 └── force-app/main/default/webapplications/<app-name>/  ← webapp dir
     ├── package.json                         ← npm scripts
-    ├── codegen.yml
     └── src/
-        └── api/graphql-operations-types.ts  ← generated types
 ```
 
 | Command | Run From | Why |
 |---------|----------|-----|
 | `npm run graphql:schema` | webapp dir | Script in webapp's package.json |
-| `npm run graphql:codegen` | webapp dir | Reads codegen.yml |
 | `npx eslint <file>` | webapp dir | Reads eslint.config.js |
-| `grep ... schema.graphql` | project root | Schema lives at root |
+| `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
 
-### Grep Patterns (from project root)
+### 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>
+```
 
-| Pattern | Context | Purpose |
-|---------|---------|---------|
-| `^type <Entity> implements Record` | `-A 100` | Entity fields |
-| `^input <Entity>_Filter` | `-A 50` | Filter options |
-| `^input <Entity>_OrderBy` | `-A 30` | Sort options |
-| `^input <Entity>CreateInput` | `-A 50` | Create mutation input |
-| `^input <Entity>UpdateInput` | `-A 50` | Update mutation input |
+| 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` | Re-grep to verify field name |
+| `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 grep
+- [ ] All field names verified via search script (Step 2)
 - [ ] `@optional` applied to record fields (reads)
 - [ ] Optional chaining in consuming code
-- [ ] `gql` tag used (not plain strings)
 - [ ] Lint passes: `npx eslint <file>`
-- [ ] Types generated: `npm run graphql:codegen`

package/dist/.a4drules/skills/using-salesforce-data/graphql-search.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# graphql-search.sh — Look up one or more Salesforce entities in schema.graphql.
+#
+# Run from the SFDX project root (where schema.graphql lives):
+#   bash .a4drules/skills/using-salesforce-data/graphql-search.sh Account
+#   bash .a4drules/skills/using-salesforce-data/graphql-search.sh Account Contact Opportunity
+#
+# Pass a custom schema path with -s / --schema:
+#   bash .a4drules/skills/using-salesforce-data/graphql-search.sh -s /path/to/schema.graphql Account
+#   bash .a4drules/skills/using-salesforce-data/graphql-search.sh --schema ./other/schema.graphql Account Contact
+#
+# Output sections per entity:
+#   1. Type definition   — all fields and relationships
+#   2. Filter options    — <Entity>_Filter input (for `where:`)
+#   3. Sort options      — <Entity>_OrderBy input (for `orderBy:`)
+#   4. Create input      — <Entity>CreateRepresentation (for create mutations)
+#   5. Update input      — <Entity>UpdateRepresentation (for update mutations)
+
+SCHEMA="./schema.graphql"
+
+# ── Argument parsing ─────────────────────────────────────────────────────────
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -s|--schema)
+      if [[ -z "${2-}" || "$2" == -* ]]; then
+        echo "ERROR: --schema requires a file path argument"
+        exit 1
+      fi
+      SCHEMA="$2"
+      shift 2
+      ;;
+    --)
+      shift
+      break
+      ;;
+    -*)
+      echo "ERROR: Unknown option: $1"
+      echo "Usage: bash $0 [-s <schema-path>] <EntityName> [EntityName2 ...]"
+      exit 1
+      ;;
+    *)
+      break
+      ;;
+  esac
+done
+
+if [ $# -eq 0 ]; then
+  echo "Usage: bash $0 [-s <schema-path>] <EntityName> [EntityName2 ...]"
+  echo "Example: bash $0 Account"
+  echo "Example: bash $0 Account Contact Opportunity"
+  echo "Example: bash $0 --schema /path/to/schema.graphql Account"
+  exit 1
+fi
+
+if [ ! -f "$SCHEMA" ]; then
+  echo "ERROR: schema.graphql not found at $SCHEMA"
+  echo "  Make sure you are running from the SFDX project root, or pass the path explicitly:"
+  echo "    bash $0 --schema <path/to/schema.graphql> <EntityName>"
+  echo "  If the file is missing entirely, generate it from the webapp dir:"
+  echo "    cd force-app/main/default/webapplications/<app-name> && npm run graphql:schema"
+  exit 1
+fi
+
+# ── Helper: extract lines from a grep match through the closing brace ────────
+# Prints up to MAX_LINES lines after (and including) the first match of PATTERN.
+# Uses a generous line count — blocks are always closed by a "}" line.
+
+extract_block() {
+  local label="$1"
+  local pattern="$2"
+  local max_lines="$3"
+
+  local match
+  match=$(grep -nE "$pattern" "$SCHEMA" | head -1)
+
+  if [ -z "$match" ]; then
+    echo "  (not found: $pattern)"
+    return
+  fi
+
+  echo "### $label"
+  grep -E "$pattern" "$SCHEMA" -A "$max_lines" | \
+    awk '/^\}$/{print; exit} {print}' | \
+    head -n "$max_lines"
+  echo ""
+}
+
+# ── Main loop ────────────────────────────────────────────────────────────────
+
+for ENTITY in "$@"; do
+  echo ""
+  echo "======================================================================"
+  echo "  SCHEMA LOOKUP: $ENTITY"
+  echo "======================================================================"
+  echo ""
+
+  # 1. Type definition — all fields and relationships
+  extract_block \
+    "Type definition — fields and relationships" \
+    "^type ${ENTITY} implements Record" \
+    200
+
+  # 2. Filter input — used in `where:` arguments
+  extract_block \
+    "Filter options — use in where: { ... }" \
+    "^input ${ENTITY}_Filter" \
+    100
+
+  # 3. OrderBy input — used in `orderBy:` arguments
+  extract_block \
+    "Sort options — use in orderBy: { ... }" \
+    "^input ${ENTITY}_OrderBy" \
+    60
+
+  # 4. Create mutation inputs
+  extract_block \
+    "Create mutation wrapper — ${ENTITY}CreateInput" \
+    "^input ${ENTITY}CreateInput" \
+    10
+
+  extract_block \
+    "Create mutation fields — ${ENTITY}CreateRepresentation" \
+    "^input ${ENTITY}CreateRepresentation" \
+    100
+
+  # 5. Update mutation inputs
+  extract_block \
+    "Update mutation wrapper — ${ENTITY}UpdateInput" \
+    "^input ${ENTITY}UpdateInput" \
+    10
+
+  extract_block \
+    "Update mutation fields — ${ENTITY}UpdateRepresentation" \
+    "^input ${ENTITY}UpdateRepresentation" \
+    100
+
+  echo ""
+done

package/dist/.a4drules/webapp-data.md

@@ -0,0 +1,353 @@
+# Salesforce Data Access
+
+- **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>`

package/dist/.a4drules/webapp-ui.md

@@ -0,0 +1,16 @@
+# UI Platform Rule
+
+**All new UI must be built as a Salesforce Web Application.**
+
+When any task involves creating a new UI, frontend, page, dashboard, form, or user-facing feature:
+
+1. Use `sf webapp generate` to scaffold the web app inside the SFDX project — do not use `create-react-app`, standalone Vite, or any other scaffold.
+2. The app must live under `<sfdx-source>/webapplications/<AppName>/` as a WebApplication bundle.
+3. Do not build new UIs as LWC components, Aura components, or Visualforce pages.
+
+Invoke the `creating-webapp` skill (`.a4drules/skills/creating-webapp/`) for the full setup workflow.
+
+## Data Access (MUST FOLLOW)
+
+- **Never hardcode data in the app.** All data displayed in the UI must come from live Salesforce data fetching — no static arrays, mock objects, or placeholder values in production code.
+- **Always invoke the `using-salesforce-data` skill** (`.a4drules/skills/using-salesforce-data/`) before writing any data access code. All implementation must be derived from that skill.

package/dist/CHANGELOG.md

@@ -3,6 +3,28 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [1.112.4](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.112.3...v1.112.4) (2026-03-20)
+
+
+### Bug Fixes
+
+* address PR [#332](https://github.com/salesforce-experience-platform-emu/webapps/issues/332) review feedback ([#336](https://github.com/salesforce-experience-platform-emu/webapps/issues/336)) ([5d499dd](https://github.com/salesforce-experience-platform-emu/webapps/commit/5d499dda12011bb201fba28d41eff1d168a2e937))
+
+
+
+
+
+## [1.112.3](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.112.2...v1.112.3) (2026-03-20)
+
+
+### Bug Fixes
+
+* **blitz:** make changes to rules and skills for blitz ([#332](https://github.com/salesforce-experience-platform-emu/webapps/issues/332)) ([f7baaa4](https://github.com/salesforce-experience-platform-emu/webapps/commit/f7baaa4d263b56ccea35b9e6bf57556edf22c530))
+
+
+
+
+
 ## [1.112.2](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.112.1...v1.112.2) (2026-03-20)
 
 **Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental

package/dist/force-app/main/default/webapplications/feature-react-global-search/package.json

@@ -15,8 +15,8 @@
     "graphql:schema": "node scripts/get-graphql-schema.mjs"
   },
   "dependencies": {
-    "@salesforce/sdk-data": "^1.112.2",
-    "@salesforce/webapp-experimental": "^1.112.2",
+    "@salesforce/sdk-data": "^1.112.4",
+    "@salesforce/webapp-experimental": "^1.112.4",
     "@tailwindcss/vite": "^4.1.17",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -43,7 +43,7 @@
     "@graphql-eslint/eslint-plugin": "^4.1.0",
     "@graphql-tools/utils": "^11.0.0",
     "@playwright/test": "^1.49.0",
-    "@salesforce/vite-plugin-webapp-experimental": "^1.112.2",
+    "@salesforce/vite-plugin-webapp-experimental": "^1.112.4",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.1.0",
     "@testing-library/user-event": "^14.5.2",

package/dist/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@salesforce/webapp-template-base-sfdx-project-experimental",
-  "version": "1.112.2",
+  "version": "1.112.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@salesforce/webapp-template-base-sfdx-project-experimental",
-      "version": "1.112.2",
+      "version": "1.112.4",
       "license": "SEE LICENSE IN LICENSE.txt",
       "devDependencies": {
         "@lwc/eslint-plugin-lwc": "^3.3.0",

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/webapp-template-base-sfdx-project-experimental",
-  "version": "1.112.2",
+  "version": "1.112.4",
   "description": "Base SFDX project template",
   "license": "SEE LICENSE IN LICENSE.txt",
   "publishConfig": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/webapp-template-feature-react-global-search-experimental",
-  "version": "1.112.2",
+  "version": "1.112.4",
   "description": "Global search feature for Salesforce objects with filtering and pagination",
   "license": "SEE LICENSE IN LICENSE.txt",
   "author": "",