@salesforce/afv-skills 1.5.1 → 1.5.2

package/skills/using-ui-bundle-salesforce-data/references/query-testing.md

@@ -0,0 +1,78 @@
+# Query Testing
+
+## Testing Method
+
+Use `sf api request rest` to POST the query to the GraphQL endpoint. Run from the **SFDX project root** (where `sfdx-project.json` lives).
+
+```bash
+sf api request rest /services/data/v66.0/graphql \
+  --method POST \
+  --body '{"query":"query GetData { uiapi { query { EntityName { edges { node { Id } } } } } }"}'
+```
+
+- Use the API version of the target org (v66.0+ for mutation support, v65.0+ for `@optional`)
+- Replace the `query` value with the generated query string
+- If the query uses variables, include them in the JSON body as a `variables` key
+
+## Critical: HTTP 200 Does Not Mean Success
+
+Salesforce returns HTTP 200 even when the GraphQL operation has errors (e.g., invalid fields, permission failures, invalid IDs). **Always parse the `errors` array in the response body regardless of HTTP status code.** Do not treat HTTP 200 as confirmation that the query succeeded.
+
+## Testing Workflow
+
+This workflow applies to both read and mutation queries:
+
+1. **Report method** — State the exact method: `sf api request rest` POST to `/services/data/vXX.0/graphql` from the project root
+2. **Ask user** — Ask the user whether they want to test the query. For mutations, also ask for input argument values — mutations modify real data, so explicit consent is essential. Wait for the user's answer before proceeding. Do not fabricate test data.
+3. **Execute test** — Only if the user explicitly agrees. Run `sf api request rest` with the query, variables, and correct API version
+4. **Report result** — Classify the result using the status definitions below. Always check the `errors` array in the response, even on HTTP 200.
+
+## Result Status Definitions
+
+| Status    | Condition                                       | Meaning                                       |
+| --------- | ----------------------------------------------- | --------------------------------------------- |
+| `SUCCESS` | `errors` is absent or empty                     | Query is valid (even if no data is returned)  |
+| `FAILED`  | `data` is empty or null                         | Query is invalid                              |
+| `PARTIAL` | `data` is present **and** `errors` is not empty | Some fields are inaccessible (mutations only) |
+
+## FAILED Status Handling
+
+The query is invalid. Follow this sequence:
+
+### 1. Error Analysis
+
+Parse the `errors` array and check `errors[].extensions.ErrorType` for Salesforce-specific error classification. Categorize into:
+
+| Category        | ErrorType / Message Contains                                     | Resolution                                                                         |
+| --------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| **Syntax**      | `InvalidSyntax`                                                  | Fix syntax errors using the error message details                                  |
+| **Validation**  | `ValidationError`                                                | Field name is likely invalid — re-run the schema search script, ask user if still unclear |
+| **Type**        | `VariableTypeMismatch` or `UnknownType`                          | Use error details and schema to correct the argument type; adjust variables        |
+| **Execution**   | `DataFetchingException`, `invalid cross reference id`            | Entity is unknown/deleted — create entity first if possible, or ask for a valid Id |
+| **Navigation**  | `is not currently available in mutation results`                 | Field cannot be in mutation output — apply PARTIAL status handling                 |
+| **Unsupported** | `OperationNotSupported`                                          | The operation is not supported — check object availability and API version         |
+| **API Version** | `Cannot invoke JsonElement.isJsonObject()` (on update mutations) | `Record` selection requires API version 64+ — report and retry with version 64     |
+
+### 2. Targeted Resolution
+
+Apply the resolution from the table above based on the error category. Update the query accordingly.
+
+### 3. Test Again
+
+Re-run the testing workflow with the updated query. Increment and track the attempt counter.
+
+## PARTIAL Status Handling
+
+The query executed but some fields are inaccessible (mutations only):
+
+1. Report the fields listed in the `errors` attribute
+2. Explain that these fields cannot be queried as part of a mutation
+3. Explain that the query will report errors if these fields remain
+4. Offer to remove the offending fields
+5. **STOP and WAIT** for the user's answer. Do NOT remove fields without explicit consent.
+6. If the user agrees, restart the mutation generation workflow with the updated field list
+
+## Retry and Escalation
+
+- **Maximum 2 test attempts** per generated query
+- If targeted resolution fails after 2 attempts, ask the user for additional details and **restart the entire workflow from Step 1 (Acquire Schema)** to re-validate entity and field information

package/skills/using-ui-bundle-salesforce-data/references/read-query-generation.md

@@ -0,0 +1,307 @@
+# Read Query Generation
+
+## Generation Rules
+
+1. **No proliferation** — Only generate for explicitly requested fields, nothing else. Do NOT add fields the user did not ask for.
+2. **Unique query** — Leverage child relationships to query entities in one single query
+3. **Navigate entities** — Always use `relationshipName` to access reference fields and child entities. Exception: if `relationshipName` is null, return the `Id` itself
+4. **Leverage fragments** — Generate one fragment per possible type on polymorphic fields (fields with `dataType="REFERENCE"` and more than one entry in `referenceToInfos`)
+5. **Type consistency** — Variables used as query arguments and their related fields must share the same GraphQL type. Verify types against the schema search script output — do not assume types
+6. **Type enforcement** — Use field type information from introspection and the GraphQL schema to generate correct field access
+7. **Field name validation** — Every field name in the generated query **MUST** match a field confirmed via the schema search script. Do NOT guess or assume field names exist
+8. **@optional for FLS** — Apply `@optional` on all Salesforce record fields when possible (see [Field-Level Security and @optional](#field-level-security-and-optional)). This lets the query succeed when the user lacks field-level access; the server omits inaccessible fields instead of failing
+9. **Consuming code defense** — When generating or modifying code that consumes read query results, defend against missing fields (see [Field-Level Security and @optional](#field-level-security-and-optional)). Use optional chaining (`?.`), nullish coalescing (`??`), and null/undefined checks — never assume optional fields are present
+10. **Semi and anti joins** — Use the semi-join or anti-join templates to filter an entity with conditions on child entities
+11. **Explicit pagination** — Always include `first:` in every query to control page size (see [Pagination](#pagination)). Default is 10 if omitted.
+12. **Respect execution limits** — Stay within SOQL-derived limits: max 10 subqueries per request, max 5 child-to-parent relationship levels, max 1 parent-to-child level (no grandchildren), max 55 child-to-parent relationships, max 20 parent-to-child relationships per query
+13. **Compound fields** — When filtering, ordering, or aggregating, use constituent fields (e.g., `BillingCity`, `BillingCountry`) not the compound wrapper (`BillingAddress`). The compound wrapper is only for selection.
+14. **`_Record` suffix awareness** — Objects added to UI API in v60+ may use a `_Record` suffix for their type name (e.g., `FeedItem_Record` instead of `FeedItem`). Always verify type names via schema lookup — do not assume type name equals sObject API name.
+15. **Query generation** — Use the read query template below
+
+## Field-Level Security and @optional
+
+Field-level security (FLS) restricts which fields different users can see. Use the `@optional` directive on Salesforce record fields when possible. The server omits the field when the user lacks access, allowing the query to succeed instead of failing. Available in API v65.0+.
+
+Apply `@optional` to:
+- Scalar fields and value-type fields (e.g. `Name { value }`)
+- Parent relationships
+- Child relationships
+
+**Consuming code must defend against missing fields.** When a field is omitted due to FLS, it will be `undefined` (or absent) in the response. Use optional chaining (`?.`), nullish coalescing (`??`), and explicit null/undefined checks when reading query results. Never assume an optional field is present.
+
+```ts
+// Defend against missing fields
+const name = node.Name?.value ?? '';
+const relatedName = node.RelationshipName?.Name?.value ?? 'N/A';
+
+// Unsafe — will throw if field omitted due to FLS
+const name = node.Name.value;
+```
+
+## Pagination
+
+Salesforce GraphQL uses Relay Cursor Connections with **forward-only pagination**. There is no backward pagination (`last`/`before` are not supported).
+
+### Core Rules
+
+- **Always specify `first:`** — If omitted, the server defaults to 10 records. Be explicit.
+- **Forward-only** — Use `first` and `after` only. Do **not** use `last` or `before` — they are unsupported and will fail.
+- **Maximum without upperBound** — Standard pagination allows up to 4,000 total records across pages.
+- **Use `pageInfo`** — Select `pageInfo { hasNextPage endCursor }` for any query that may need pagination.
+
+### UpperBound Pagination (v59+)
+
+When you need more than 200 records per page or more than 4,000 total records, switch to upperBound mode:
+
+- **`first` must be 200–2000** when `upperBound` is set. Values below 200 are invalid.
+- **`upperBound`** declares the estimated total record count and enables extended pagination.
+
+```graphql
+# Standard pagination
+Account(first: 50, after: $cursor) {
+  edges { node { Id Name @optional { value } } }
+  pageInfo { hasNextPage endCursor }
+}
+
+# UpperBound pagination for large result sets
+Account(first: 2000, after: $cursor, upperBound: 10000) {
+  edges { node { Id Name @optional { value } } }
+  pageInfo { hasNextPage endCursor }
+}
+```
+
+## Ordering
+
+Use the `orderBy:` argument with generated `<Object>_OrderBy` input types. Run the schema search script to verify sortable fields.
+
+### Rules
+
+- Use `orderBy:` with the generated OrderBy type: `orderBy: { FieldName: { order: ASC } }`
+- **Multi-column sorting** is supported by combining fields in the orderBy input
+- **Unsupported field types** for ordering: multi-select picklist, rich text, long text area, encrypted fields. Do not order by these.
+- **Locale sensitivity** — Sort order depends on user locale. For deterministic ordering, add `Id` as a tie-breaker field.
+- **Compound fields** — Use constituent fields for ordering (e.g., `BillingCity`), not the compound wrapper.
+
+```graphql
+Account(
+  first: 10,
+  orderBy: { Name: { order: ASC }, CreatedDate: { order: DESC } }
+) { ... }
+```
+
+## Filtering
+
+### Boolean Filter Composition
+
+Filter types include `AND`, `OR`, and `NOT` fields for combining conditions. Multiple filter fields at the same level combine with implicit AND.
+
+```graphql
+# Implicit AND — both conditions must match
+Account(where: { Industry: { eq: "Technology" }, AnnualRevenue: { gt: 1000000 } })
+
+# Explicit OR
+Account(where: { OR: [
+  { Industry: { eq: "Technology" } },
+  { Industry: { eq: "Finance" } }
+] })
+
+# NOT
+Account(where: { NOT: { Industry: { eq: "Technology" } } })
+```
+
+### Date and DateTime Filtering
+
+Date and DateTime fields use special input objects (`DateInput`/`DateTimeInput`) that support both literal values and SOQL-style relative date semantics.
+
+```graphql
+# Literal date
+Opportunity(where: { CloseDate: { eq: { value: "2024-12-31" } } })
+
+# Relative date literal
+Opportunity(where: { CloseDate: { gte: { literal: TODAY } } })
+```
+
+Verify exact literal enum values (e.g., `TODAY`, `THIS_MONTH`) via the schema search script.
+
+### String Equality Is Case-Insensitive
+
+String comparisons with `eq` are case-insensitive in Salesforce GraphQL. Do not rely on case sensitivity for string equality filters.
+
+### Relationship Filters
+
+Filter through parent relationships using nested filter objects (not dot notation):
+
+```graphql
+# Correct — nested filter objects
+Contact(where: { Account: { Name: { like: "Acme%" } } })
+
+# Wrong — dot notation is not supported
+Contact(where: { "Account.Name": { like: "Acme%" } })
+```
+
+### Polymorphic Relationship Filters
+
+Polymorphic relationships use union-aware filter input types named `<Object>_<RelationshipName>_Filters`. Filter by specific concrete types within the union:
+
+```graphql
+# Filter by polymorphic Owner (which is a union of User, Group, etc.)
+Account(where: { Owner: { User: { Username: { like: "admin%" } } } })
+```
+
+Verify exact filter input type names and available concrete types via the schema search script.
+
+### ID Filtering
+
+Salesforce accepts both 15-character and 18-character record IDs for `Id` filtering. Do not reject or "correct" either form.
+
+## Semi-Join and Anti-Join Templates
+
+Semi-joins and anti-joins filter a parent entity using conditions on child entities. They use `inq` (semi-join) and `ninq` (anti-join) operators on the parent entity's `Id`.
+
+The operator accepts:
+
+- The child entity camelCase name with conditions
+- The `ApiName` field containing the parent entity `Id` (`fieldName` from `childRelationships`)
+
+If the only condition is child entity existence, use `Id: { ne: null }`.
+
+### Restrictions
+
+Semi-join and anti-join queries have SOQL-derived restrictions:
+- **Limited count** — There are limits on the number of `inq`/`ninq` operators per query
+- **No `ne` with joins** — Cannot use `ne` operator in combination with join operators
+- **No `or` in subquery** — The join subquery conditions cannot use `OR`
+- **No `orderBy` in subquery** — Join subqueries do not support ordering
+- **Nesting restrictions** — Semi/anti-joins cannot be nested within each other
+
+### Semi-Join Example
+
+Filter `ParentEntity` to include only those with at least one matching `ChildEntity`:
+
+```graphql
+query testSemiJoin {
+  uiapi {
+    query {
+      ParentEntity(
+        where: {
+          Id: {
+            inq: {
+              ChildEntity: {
+                Name: { like: "test%" }
+                Type: { eq: "some value" }
+              }
+              ApiName: "parentIdFieldInChild"
+            }
+          }
+        }
+      ) {
+        edges {
+          node {
+            Id
+            Name @optional {
+              value
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Anti-Join Example
+
+Same as the semi-join example, but replace `inq` with `ninq` to filter `ParentEntity` with **no** matching `ChildEntity`.
+
+## Current User Exception
+
+To retrieve **current user**, **connected user**, or **authenticated user** information, use `uiapi.currentUser` instead of the standard query pattern. This field takes **no arguments** and returns a `User` type.
+
+## Conditional Field Selection
+
+For dynamic fieldsets with **known** fields, use `@include(if: $condition)` and `@skip(if: $condition)` directives in `.graphql` files. See GraphQL spec for details.
+
+## Read Query Template
+
+```graphql
+query QueryName($after: String) {
+  uiapi {
+    query {
+      EntityName(
+        first: 10         # Always specify — default is 10 if omitted
+        after: $after      # For pagination
+        where: { ... }     # Filter conditions
+        orderBy: { ... }   # Sort order
+      ) {
+        edges {
+          node {
+            # Direct fields — use @optional for FLS resilience
+            FieldName @optional { value }
+
+            # Non-polymorphic reference (single type)
+            RelationshipName @optional {
+              Id
+              Name { value }
+            }
+
+            # Polymorphic reference (multiple types)
+            PolymorphicRelationshipName @optional {
+              ...TypeAInfo
+              ...TypeBInfo
+            }
+
+            # Child relationship (subquery) — max 1 level deep, no grandchildren
+            RelationshipName @optional (
+              first: 10     # Always specify
+            ) {
+              edges {
+                node {
+                  # fields
+                }
+              }
+            }
+          }
+        }
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+      }
+    }
+  }
+}
+
+fragment TypeAInfo on TypeA {
+  Id
+  SpecificFieldA @optional { value }
+}
+
+fragment TypeBInfo on TypeB {
+  Id
+  SpecificFieldB @optional { value }
+}
+```
+
+## Field Value Wrappers
+
+Schema fields use typed wrappers. Access the underlying value via `.value`:
+
+| Wrapper Type      | Underlying Type | Access Pattern        |
+| ----------------- | --------------- | --------------------- |
+| `StringValue`     | `String`        | `field { value }`     |
+| `IntValue`        | `Int`           | `field { value }`     |
+| `CurrencyValue`   | `Currency`      | `field { value }`     |
+| `DateTimeValue`   | `DateTime`      | `field { value }`     |
+| `PicklistValue`   | `Picklist`      | `field { value }`     |
+| `BooleanValue`    | `Boolean`       | `field { value }`     |
+| `DoubleValue`     | `Double`        | `field { value }`     |
+| `PercentValue`    | `Percent`       | `field { value }`     |
+| `IDValue`         | `ID`            | `field { value }`     |
+| `EmailValue`      | `Email`         | `field { value }`     |
+| `PhoneNumberValue`| `PhoneNumber`   | `field { value }`     |
+| `UrlValue`        | `Url`           | `field { value }`     |
+| `DateValue`       | `Date`          | `field { value }`     |
+| `LongValue`       | `Long`          | `field { value }`     |
+| `TextAreaValue`   | `TextArea`      | `field { value }`     |
+
+All wrappers also expose `displayValue: String` for formatted display. `displayValue` is server-rendered using SOQL `toLabel()` or `format()` depending on field type — use it for UI display instead of formatting values client-side.

package/skills/using-ui-bundle-salesforce-data/references/schema-introspection.md

@@ -0,0 +1,53 @@
+# Schema Introspection
+
+## Schema Access Policy
+
+The `schema.graphql` file is **265,000+ lines**. Loading it into context or opening it in an editor will overwhelm the context window or crash tools.
+
+Do not use cat, less, more, head, tail, editors (VS Code, vim, nano), or programmatic parsers (node, python, awk, sed, jq) on `schema.graphql`. Use the schema search script or targeted grep calls only.
+
+## Schema Lookup
+
+Run the search script from the **SFDX project root** to get all relevant schema info in one step:
+
+```bash
+bash scripts/graphql-search.sh <EntityName>
+# Multiple entities:
+bash scripts/graphql-search.sh Account Contact Opportunity
+```
+
+**Maximum 2 script runs.** If the entity still can't be found after checking naming variations, ask the user.
+
+## Entity Identification
+
+Map user intent to PascalCase entity names:
+
+1. Convert natural language to PascalCase (e.g., "accounts" → `Account`, "case comments" → `CaseComment`, "custom objects" → `CustomObject__c`)
+2. Run the schema search script to validate the entity exists
+3. If a candidate does not match, try:
+   - `__c` suffix for custom objects, `__e` for platform events
+   - **`_Record` suffix** — Objects added to UI API in API v60+ may use `<EntityName>_Record` as their type name (e.g., `FeedItem_Record` instead of `FeedItem`)
+4. If an entity cannot be resolved, **ask the user** for the correct name — do not guess
+
+## Iterative Introspection
+
+Use a maximum of **3 introspection cycles** to resolve all entities and their dependencies:
+
+1. **Introspect** — Run the schema search script for each unresolved entity
+2. **Fields** — Extract requested field names and types from the type definition output
+3. **References** — Identify reference fields. If a reference resolves to multiple types, mark it as **polymorphic** (use inline fragments in the generated query). Add newly discovered entity types to the working list.
+4. **Child relationships** — Identify Connection types (e.g., `Contacts: ContactConnection`). Add child entity types to the working list.
+5. **Next cycle** — If unresolved entities remain and the cycle limit hasn't been reached, repeat from step 1
+
+### Hard Stop Rules
+
+- If no introspection data is returned for an entity, **stop** — the entity may not be deployed
+- If unknown entities remain after 3 cycles, **stop** — ask the user for clarification
+- Do not proceed with query generation until all entities and requested fields are confirmed in the schema
+
+## Deployment Prerequisites
+
+The schema reflects the **current org state**. Custom objects and fields appear only after metadata is deployed.
+
+- **Before** running `npm run graphql:schema`: Deploy all metadata and assign permission sets. Invoke the `deploying-ui-bundle` skill for the full sequence.
+- **After** any metadata deployment: Re-run `npm run graphql:schema` and `npm run graphql:codegen` so types and queries stay in sync.

package/skills/using-ui-bundle-salesforce-data/references/ui-bundle-integration.md

@@ -0,0 +1,221 @@
+# UI Bundle Integration
+
+## When to Use
+
+This guide applies when integrating GraphQL queries into a React UI bundle using `createDataSDK` + codegen from `@salesforce/sdk-data`.
+
+## Core Types & Function Signatures
+
+### createDataSDK and graphql
+
+```typescript
+import { createDataSDK } from "@salesforce/sdk-data";
+
+const sdk = await createDataSDK();
+const response = await sdk.graphql?.<ResponseType, VariablesType>(query, variables);
+```
+
+`createDataSDK()` returns a `DataSDK` instance. The `graphql` method uses optional chaining (`?.`) because not all surfaces support GraphQL.
+
+### gql Template Tag
+
+```typescript
+import { gql } from "@salesforce/sdk-data";
+
+const MY_QUERY = gql`
+  query MyQuery {
+    uiapi { ... }
+  }
+`;
+```
+
+The `gql` tag enables ESLint validation against the schema. Plain template strings bypass validation.
+
+### NodeOfConnection
+
+```typescript
+import { type NodeOfConnection } from "@salesforce/sdk-data";
+
+type AccountNode = NodeOfConnection<GetHighRevenueAccountsQuery["uiapi"]["query"]["Account"]>;
+```
+
+Use `NodeOfConnection` to extract the node type from a Connection type for cleaner typing.
+
+## Query Patterns
+
+Choose the pattern based on query complexity:
+
+- **Pattern 1 — External `.graphql` file**: Recommended for complex queries with variables, fragments, or shared across files. Full codegen support, syntax highlighting, shareable. Requires codegen step after changes. Does NOT support dynamic queries.
+- **Pattern 2 — Inline `gql` tag**: Recommended for simple queries. Supports dynamic queries (field set varies at runtime). **MUST use `gql` tag** — plain template strings bypass `@graphql-eslint` validation.
+
+## Pattern 1: External .graphql File
+
+Create a `.graphql` file, run `npm run graphql:codegen`, import with `?raw` suffix, and use generated types.
+
+**Required imports:**
+
+```typescript
+import { createDataSDK, type NodeOfConnection } from "@salesforce/sdk-data";
+import MY_QUERY from "./query/myQuery.graphql?raw"; // ?raw suffix required
+import type { GetMyDataQuery, GetMyDataQueryVariables } from "../graphql-operations-types";
+```
+
+**Example usage:**
+
+```typescript
+const sdk = await createDataSDK();
+const response = await sdk.graphql?.<GetMyDataQuery, GetMyDataQueryVariables>(
+  MY_QUERY,
+  variables
+);
+
+if (response?.errors?.length) {
+  throw new Error(response.errors.map((e) => e.message).join("; "));
+}
+
+const nodes = response?.data?.uiapi?.query?.EntityName?.edges?.map((e) => e.node) ?? [];
+```
+
+## Pattern 2: Inline gql Tag
+
+**Required imports:**
+
+```typescript
+import { createDataSDK, gql } from "@salesforce/sdk-data";
+import { type CurrentUserQuery } from "../graphql-operations-types";
+
+const MY_QUERY = gql`
+  query CurrentUser {
+    uiapi { ... }
+  }
+`;
+```
+
+> **MUST use `gql` tag** — plain template strings bypass the `@graphql-eslint` processor entirely, meaning no lint validation against the schema.
+
+## Error Handling Strategies
+
+**Strategy A — Strict (default):** Treat any errors as failure.
+
+```typescript
+if (response?.errors?.length) {
+  throw new Error(response.errors.map((e) => e.message).join("; "));
+}
+const result = response?.data;
+```
+
+**Strategy B — Tolerant:** Log errors but use available data.
+
+```typescript
+if (response?.errors?.length) {
+  console.warn("GraphQL partial errors:", response.errors);
+}
+const result = response?.data;
+```
+
+**Strategy C — Discriminated:** Fail only when no data is returned. Useful for mutations where some return fields may be inaccessible.
+
+```typescript
+if (!response?.data && response?.errors?.length) {
+  throw new Error(response.errors.map((e) => e.message).join("; "));
+}
+const result = response?.data;
+```
+
+Responses follow `uiapi.query.ObjectName.edges[].node`; fields use `{ value }`.
+
+## Conditional Field Selection
+
+For dynamic fieldsets with **known** fields, use `@include(if: $condition)` and `@skip(if: $condition)` directives in `.graphql` files. See GraphQL spec for details.
+
+## ESLint Validation
+
+After writing the query into a source file, validate it against the schema:
+
+```bash
+# Run from UI bundle dir (force-app/main/default/uiBundles/<app-name>/)
+npx eslint <path-to-file-containing-query>
+```
+
+**How it works:** The ESLint config uses `@graphql-eslint/eslint-plugin` with its `processor`, which extracts GraphQL operations from `gql` template literals in `.ts`/`.tsx` files and validates the extracted `.graphql` virtual files against `schema.graphql`.
+
+**Rules enforced:** `no-anonymous-operations`, `no-duplicate-fields`, `known-fragment-names`, `no-undefined-variables`, `no-unused-variables`
+
+**On failure:** Fix the reported issues, re-run `npx eslint <file>` until clean, then proceed to testing.
+
+> **Prerequisites**: The `schema.graphql` file must exist and project dependencies must be installed (`npm install`).
+
+## Codegen
+
+Generate TypeScript types from `.graphql` files and inline `gql` queries:
+
+```bash
+# Run from UI bundle dir (force-app/main/default/uiBundles/<app-name>/)
+npm run graphql:codegen
+```
+
+Output: `src/api/graphql-operations-types.ts`
+
+Naming conventions:
+- `<OperationName>Query` / `<OperationName>Mutation` — response types
+- `<OperationName>QueryVariables` / `<OperationName>MutationVariables` — variable types
+
+## Anti-Patterns
+
+### Direct API Calls
+
+```typescript
+// NOT RECOMMENDED: Direct axios/fetch calls for GraphQL
+// PREFERRED: Use the Data SDK
+const sdk = await createDataSDK();
+const response = await sdk.graphql?.<ResponseType>(query, variables);
+```
+
+### Missing Type Definitions
+
+```typescript
+// NOT RECOMMENDED: Untyped GraphQL calls
+// PREFERRED: Provide response type
+const response = await sdk.graphql?.<GetMyDataQuery>(query);
+```
+
+### Plain String Queries (Without gql Tag)
+
+```typescript
+// NOT RECOMMENDED: Plain strings bypass ESLint validation
+const query = `query { ... }`;
+
+// PREFERRED: Use gql tag for inline queries
+const QUERY = gql`query { ... }`;
+```
+
+## Quality Checklists
+
+### For Pattern 1 (.graphql files):
+
+1. [ ] All field names verified via schema search script
+2. [ ] Create `.graphql` file for the query/mutation
+3. [ ] Run `npm run graphql:codegen` to generate types
+4. [ ] Import query with `?raw` suffix
+5. [ ] Import generated types from `graphql-operations-types.ts`
+6. [ ] Use `sdk.graphql?.<ResponseType>()` with proper generic
+7. [ ] Handle `response.errors` and destructure `response.data`
+8. [ ] Use `NodeOfConnection` for cleaner node types when needed
+9. [ ] Run `npx eslint <file>` from UI bundle dir — fix all GraphQL errors
+
+### For Pattern 2 (inline with gql):
+
+1. [ ] All field names verified via schema search script
+2. [ ] Define query using `gql` template tag (NOT a plain string)
+3. [ ] Ensure query name matches generated types in `graphql-operations-types.ts`
+4. [ ] Import generated types for the query
+5. [ ] Use `sdk.graphql?.<ResponseType>()` with proper generic
+6. [ ] Handle `response.errors` and destructure `response.data`
+7. [ ] Run `npx eslint <file>` from UI bundle dir — fix all GraphQL errors
+
+### General:
+
+- [ ] Lint validation passes (`npx eslint <file>` reports no GraphQL errors)
+- [ ] Query field names match the schema exactly (case-sensitive)
+- [ ] Response type generic is provided to `sdk.graphql?.<T>()`
+- [ ] Optional chaining is used for nested response data