@salesforce/webapp-template-feature-react-chart-experimental 1.105.0 → 1.106.0

package/dist/.a4drules/skills/salesforce-graphql/SKILL.md

@@ -0,0 +1,323 @@
+---
+name: salesforce-graphql
+description: Salesforce GraphQL data access. Use when the user asks to fetch, query, or mutate Salesforce data, or add a GraphQL operation for an object like Account, Contact, or Opportunity.
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.graphql"
+---
+
+# Salesforce GraphQL
+
+Guidance for querying and mutating Salesforce data via the Salesforce GraphQL API. Use `createDataSDK()` + `sdk.graphql?.()` and codegen tooling.
+
+## When to Use
+
+- User asks to "fetch data from Salesforce"
+- User asks to "query" or "mutate" Salesforce records
+- User wants to add a new GraphQL operation (query or mutation)
+- User asks to add data access for a Salesforce object (Account, Contact, Opportunity, etc.)
+
+## Schema Access Policy (GREP ONLY)
+
+> **GREP ONLY** — The `schema.graphql` file is very large (~265,000+ lines). All schema lookups **MUST** use the grep-only commands defined in the `salesforce-graphql-explore-schema` skill. Do NOT open, read, stream, or parse `./schema.graphql` with any tool other than grep.
+
+## Directory Context
+
+The generated app has a two-level directory structure. Commands must run from the correct directory.
+
+```
+<project-root>/                                            ← SFDX project root
+├── schema.graphql                                         ← grep target
+├── sfdx-project.json
+└── force-app/main/default/webapplications/<app-name>/     ← webapp dir
+    ├── package.json         (npm scripts: graphql:schema, graphql:codegen, lint)
+    ├── eslint.config.js     (schema ref: ../../../../../schema.graphql)
+    ├── codegen.yml          (schema ref: ../../../../../schema.graphql)
+    └── src/                 (source code, .graphql query files)
+```
+
+| Command                   | Run from         | Why                                    |
+| ------------------------- | ---------------- | -------------------------------------- |
+| `npm run graphql:schema`  | **webapp dir**   | Script is in webapp's `package.json`   |
+| `npm run graphql:codegen` | **webapp dir**   | Reads `codegen.yml` in webapp dir       |
+| `npx eslint <file>`      | **webapp dir**   | Reads `eslint.config.js` in webapp dir |
+| `grep ... schema.graphql` | **project root** | `schema.graphql` lives at project root |
+| `sf api request graphql` | **project root** | Needs `sfdx-project.json`              |
+
+> **Wrong directory = silent failures.** `npm run graphql:schema` from the project root will fail with "missing script." `grep ./schema.graphql` from the webapp dir will fail with "no such file."
+
+## Prerequisites
+
+The base React app (`base-react-app`) ships with all GraphQL dependencies and tooling pre-configured:
+
+- `@salesforce/sdk-data` — runtime SDK for `createDataSDK` and `gql`
+- `@graphql-codegen/cli` + plugins — type generation from `.graphql` files and inline `gql` queries
+- `@graphql-eslint/eslint-plugin` — validates `.graphql` files and `gql` template literals against `schema.graphql` (used as a query validation gate — see Step 6)
+- `graphql` — shared by codegen, ESLint, and schema introspection
+
+Before using this skill, ensure:
+
+1. The `@salesforce/sdk-data` package is available (provides `createDataSDK`, `gql`, `NodeOfConnection`)
+2. A `schema.graphql` file exists at the project root. If missing, generate it:
+   ```bash
+   # Run from webapp dir (force-app/main/default/webapplications/<app-name>/)
+   npm run graphql:schema
+   ```
+
+## npm Scripts
+
+- **`npm run graphql:schema`** — _(run from webapp dir)_ Downloads the full GraphQL schema from a connected Salesforce org via introspection. Outputs `schema.graphql` to the project root.
+- **`npm run graphql:codegen`** — _(run from webapp dir)_ Generates TypeScript types from `.graphql` files and inline `gql` queries. Outputs to `src/api/graphql-operations-types.ts`.
+
+## Workflow
+
+### Step 1: Download Schema
+
+Ensure `schema.graphql` exists at the project root. If missing, run `npm run graphql:schema` from the webapp dir.
+
+### Step 2: Explore the Schema (grep-only)
+
+Before writing any query, verify the target object and its fields exist in the schema.
+
+**Invoke the `salesforce-graphql-explore-schema` skill** for the full exploration workflow and **mandatory grep-only access policy**.
+
+> **GREP ONLY** — All schema lookups MUST use the grep commands defined in the `salesforce-graphql-explore-schema` skill. Do NOT open, read, stream, or parse `./schema.graphql` with any tool other than grep.
+
+Key actions (all via grep):
+
+- `type <ObjectName> implements Record` — find available fields
+- `input <ObjectName>_Filter` — find filter options
+- `input <ObjectName>_OrderBy` — find sorting options
+- `input <ObjectName>CreateInput` / `<ObjectName>UpdateInput` — find mutation input types
+
+### Step 3: Choose the Query Pattern
+
+**Pattern 1 — External `.graphql` file** (recommended for complex queries):
+
+- Queries with variables, fragments, or shared across files
+- Full codegen support, syntax highlighting, shareable
+- Requires codegen step after changes
+- See example: `api/utils/accounts.ts` + `api/utils/query/highRevenueAccountsQuery.graphql`
+
+**Pattern 2 — Inline `gql` tag** (recommended for simple queries):
+
+- Simple queries without variables; colocated with usage code
+- Supports dynamic queries (field set varies at runtime)
+- **MUST use `gql` tag** — plain template strings bypass `@graphql-eslint` validation
+- See example: `api/utils/user.ts`
+
+### Step 4: Write the Query
+
+For **Pattern 1**:
+
+1. Create a `.graphql` file under `src/api/utils/query/`
+2. Follow UIAPI structure: `query { uiapi { query { ObjectName(...) { edges { node { ... } } } } } }`
+3. For mutations, invoke the `salesforce-graphql-mutation-query` skill
+4. For read queries, invoke the `salesforce-graphql-read-query` skill
+
+For **Pattern 2**:
+
+1. Define query inline using the `gql` template tag
+2. Ensure the query name matches what codegen expects
+
+### Step 5: Test Queries Against Live Org
+
+Use the testing workflows in the `salesforce-graphql-read-query` and `salesforce-graphql-mutation-query` skills to validate queries against the connected org before integrating into the app.
+
+### Step 6: Generate Types
+
+```bash
+# Run from webapp dir (force-app/main/default/webapplications/<app-name>/)
+npm run graphql:codegen
+```
+
+This updates `src/api/graphql-operations-types.ts` with `<OperationName>Query`/`<OperationName>Mutation` and `<OperationName>QueryVariables`/`<OperationName>MutationVariables`.
+
+### Step 7: Lint Validate
+
+Run ESLint on the file containing the query to validate it against the schema **before** any live testing:
+
+```bash
+# Run from webapp dir
+npx eslint <path-to-file>
+```
+
+The `@graphql-eslint/eslint-plugin` processor extracts GraphQL from `gql` template literals and validates them against `schema.graphql`. Fix all ESLint errors before proceeding.
+
+### Step 8: Implement and Verify
+
+Implement the data access function using the pattern below. Use the Quality Checklist before completing.
+
+---
+
+## 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.
+
+### Error Handling
+
+Default: treat any errors as failure (Strategy A). For partial data tolerance, log errors but use data. For mutations where some return fields are inaccessible, use Strategy C (fail only when no data).
+
+```typescript
+// Default: strict
+if (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 }`.
+
+### NodeOfConnection
+
+```typescript
+import { type NodeOfConnection } from "@salesforce/sdk-data";
+
+type AccountNode = NodeOfConnection<GetHighRevenueAccountsQuery["uiapi"]["query"]["Account"]>;
+```
+
+---
+
+## 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";
+```
+
+**When to use:** Complex queries with variables, fragments, or shared across files. Does NOT support dynamic queries (field set varies at runtime).
+
+---
+
+## 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.
+
+**When to use:** Simple, colocated queries. Supports dynamic queries (field set varies at runtime).
+
+---
+
+## Conditional Field Selection
+
+For dynamic fieldsets with **known** fields, use `@include(if: $condition)` and `@skip(if: $condition)` in `.graphql` files. See GraphQL spec for details.
+
+---
+
+## Anti-Patterns (Not Recommended)
+
+### 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 Checklist
+
+> If you have not completed the workflow above, **stop and complete it first**. Invoke the skill workflow before using this checklist.
+
+Before completing GraphQL data access code:
+
+### For Pattern 1 (.graphql files):
+
+1. [ ] All field names verified via grep against `schema.graphql` (invoke `salesforce-graphql-explore-schema`)
+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 webapp dir — fix all GraphQL errors
+
+### For Pattern 2 (inline with gql):
+
+1. [ ] All field names verified via grep against `schema.graphql`
+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 webapp 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, confirmed via grep)
+- [ ] Response type generic is provided to `sdk.graphql?.<T>()`
+- [ ] Optional chaining is used for nested response data
+
+---
+
+## Reference
+
+- Schema exploration: invoke the `salesforce-graphql-explore-schema` skill
+- Read query generation: invoke the `salesforce-graphql-read-query` skill
+- Mutation query generation: invoke the `salesforce-graphql-mutation-query` skill
+- Shared GraphQL schema types: `shared-schema.graphqls` (in this skill directory)
+- Schema download: `npm run graphql:schema` (run from webapp dir)
+- Type generation: `npm run graphql:codegen` (run from webapp dir)

package/dist/.a4drules/skills/salesforce-graphql-explore-schema/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: salesforce-graphql-explore-schema
+description: Explore the Salesforce GraphQL schema via grep-only lookups. Use before generating any GraphQL query — schema exploration must complete first.
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.graphql"
+---
+
+# Salesforce GraphQL Schema Exploration
+
+Guidance for AI agents working with the Salesforce GraphQL API schema. **GREP ONLY** — the schema file is very large (~265,000+ lines). All lookups MUST use grep; do NOT open, read, stream, or parse the file.
+
+## Schema File Location
+
+**Location:** `schema.graphql` at the **SFDX project root** (NOT inside the webapp dir). All grep commands **must be run from the project root** where `schema.graphql` lives.
+
+> ⚠️ **Important (Access Policy - GREP ONLY)**: Do NOT open, view, stream, paginate, or parse the schema with any tool other than grep. All lookups MUST be done via grep using anchored patterns with minimal context as defined below.
+
+If the file is not present, generate it by running (from the **webapp dir**, not the project root):
+
+```bash
+# Run from webapp dir (force-app/main/default/webapplications/<app-name>/)
+npm run graphql:schema
+```
+
+**BEFORE generating any GraphQL query, you MUST:**
+
+1. **Check if schema exists**: Look for `schema.graphql` in the **SFDX project root**
+2. **If schema is missing**:
+   - `cd` to the **webapp dir** and run `npm run graphql:schema` to download it
+   - Wait for the command to complete successfully
+   - Then proceed with grep-only lookups as defined below.
+3. **If schema exists**: Proceed with targeted searches as described below
+
+> ⚠️ **DO NOT** generate GraphQL queries without first having access to the schema. Standard field assumptions may not match the target org's configuration.
+
+## Schema Structure Overview
+
+Main entry points: `Query { uiapi }` for reads; `Mutation { uiapi(input: ...) }` for creates/updates/deletes. Record queries use `uiapi.query.<ObjectName>`.
+
+## Allowed Lookups (grep-only)
+
+Use ONLY these grep commands to locate specific definitions in schema.graphql. Do not use editors (VS Code/vim/nano), cat/less/more/head/tail, or programmatic parsers (node/python/awk/sed/jq).
+
+- Always include:
+  - `-n` (line numbers) and `-E` (extended regex)
+  - Anchors (`^`) and word boundaries (`\b`)
+  - Minimal context with `-A N` (prefer the smallest N that surfaces the needed lines)
+
+### 1. Find Available Fields for a Record Type
+
+Search for `type <ObjectName> implements Record` to find all queryable fields:
+
+```bash
+# Example: Find Account fields (anchored, minimal context)
+grep -nE '^type[[:space:]]+Account[[:space:]]+implements[[:space:]]+Record\b' ./schema.graphql -A 60
+```
+
+### 2. Find Filter Options for a Record Type
+
+Search for `input <ObjectName>_Filter` to find filterable fields and operators:
+
+```bash
+# Example: Find Account filter options (anchored)
+grep -nE '^input[[:space:]]+Account_Filter\b' ./schema.graphql -A 40
+```
+
+### 3. Find OrderBy Options
+
+Search for `input <ObjectName>_OrderBy` for sorting options:
+
+```bash
+# Example: Find Account ordering options (anchored)
+grep -nE '^input[[:space:]]+Account_OrderBy\b' ./schema.graphql -A 30
+```
+
+### 4. Find Mutation Operations
+
+Search for operations in `UIAPIMutations`:
+
+```bash
+# Example: Find Account mutations (extended regex)
+grep -nE 'Account.*(Create|Update|Delete)' ./schema.graphql
+```
+
+### 5. Find Input Types for Mutations
+
+Search for `input <ObjectName>CreateInput` or `input <ObjectName>UpdateInput`:
+
+```bash
+# Example: Find Account create input (anchored)
+grep -nE '^input[[:space:]]+AccountCreateInput\b' ./schema.graphql -A 30
+```
+
+## Common Operator Types
+
+- **StringOperators**: `eq`, `ne`, `like`, `lt`, `gt`, `lte`, `gte`, `in`, `nin`
+- **OrderByClause**: `order: ResultOrder` (ASC/DESC), `nulls: NullOrder` (FIRST/LAST)
+
+## Field Value Wrappers
+
+Salesforce GraphQL returns field values wrapped in typed objects:
+
+| Wrapper Type    | Access Pattern                     |
+| --------------- | ---------------------------------- |
+| `StringValue`   | `FieldName { value }`              |
+| `IntValue`      | `FieldName { value }`              |
+| `BooleanValue`  | `FieldName { value }`              |
+| `DateTimeValue` | `FieldName { value displayValue }` |
+| `PicklistValue` | `FieldName { value displayValue }` |
+| `CurrencyValue` | `FieldName { value displayValue }` |
+
+## Agent Workflow for Building Queries (grep-only)
+
+**Pre-requisites (MANDATORY):**
+
+- [ ] Verified `schema.graphql` exists in the **SFDX project root**
+- [ ] If missing, ran `npm run graphql:schema` from the **webapp dir** and waited for completion
+- [ ] Confirmed connection to correct Salesforce org (if downloading fresh schema)
+
+**Workflow Steps:**
+
+1. **Identify the target object** (e.g., Account, Contact, Opportunity)
+2. **Run the "Find Available Fields" grep command** for your object (copy only the field names visible in the grep output; do not open the file)
+3. **Run the "Find Filter Options" grep command** (`<Object>_Filter`) to understand filtering options
+4. **Run the "Find OrderBy Options" grep command** (`<Object>_OrderBy`) for sorting capabilities
+5. **Build the query** following the patterns in the `salesforce-graphql-read-query` or `salesforce-graphql-mutation-query` skill using only values returned by grep
+6. **Validate field names** using grep matches (case-sensitive). Do not open or parse the file beyond grep.
+
+## Tips for Agents
+
+- **Always verify field names** by running the specific grep commands; do not open the schema file
+- **Use grep with anchors and minimal -A context** to explore the schema efficiently—never read or stream the file
+- **Check relationships** by looking for `parentRelationship` and `childRelationship` comments in type definitions
+- **Look for Connection types** (e.g., `AccountConnection`) via grep to understand pagination structure
+- **Custom objects** end with `__c` (e.g., `CustomObject__c`)
+- **Custom fields** also end with `__c` (e.g., `Custom_Field__c`)
+
+## Forbidden Operations
+
+To prevent accidental large reads, the following are prohibited for schema.graphql:
+
+- Opening in any editor (VS Code, vim, nano)
+- Using cat, less, more, head, or tail
+- Programmatic parsing (node, python, awk, sed, jq)
+- Streaming or paginating through large portions of the file
+
+If any of the above occurs, stop and replace the action with one of the Allowed Lookups (grep-only).
+
+## Output Minimization
+
+- Prefer precise, anchored patterns with word boundaries
+- Use the smallest `-A` context that surfaces required lines
+- If results are noisy, refine the regex rather than increasing context
+
+## Related Skills
+
+- For generating read queries, invoke the `salesforce-graphql-read-query` skill
+- For generating mutation queries, invoke the `salesforce-graphql-mutation-query` skill

package/dist/.a4drules/skills/{feature-graphql-graphql-data-access/docs/generate-mutation-query.md → salesforce-graphql-mutation-query/SKILL.md}

@@ -1,40 +1,47 @@
-# GraphQL Mutation Query Generation
+---
+name: salesforce-graphql-mutation-query
+description: Generate Salesforce GraphQL mutation queries. Use when the query to generate is a mutation query. Schema exploration must complete first — invoke salesforce-graphql-explore-schema first.
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.graphql"
+---
+
+# Salesforce GraphQL Mutation Query Generation
 
 **Triggering conditions**
 
-1. Only if the schema exploration phase completed successfully
+1. Only if the schema exploration phase completed successfully (invoke `salesforce-graphql-explore-schema` first)
 2. Only if the query to generate is a mutation query
 
-## Your Role
+## Schema Access Policy
 
-You are a GraphQL expert and your role is to help generate Salesforce compatible GraphQL mutation queries once the exploration phase has completed.
+> ⚠️ **GREP ONLY** — During mutation generation you may need to verify field names, input types, or representations. All schema lookups **MUST** use the grep-only commands defined in the `salesforce-graphql-explore-schema` skill. Do NOT open, read, stream, or parse `./schema.graphql` with any tool other than grep.
 
-You will leverage the context provided by the requesting user as well as the validation phase provided by the schema exploration. This tool will also provide you with a method to dynamically query the target org instance that you will use to test the generated query.
+## Your Role
 
-If the schema exploration has not been executed yet, you **MUST** run it first, and then get back to mutation query generation.
+You are a GraphQL expert. Generate Salesforce-compatible mutation queries. Schema exploration must complete first. If the schema exploration has not been executed yet, you **MUST** run the full exploration workflow from the `salesforce-graphql-explore-schema` skill first, then return here for mutation query generation.
 
 ## Mutation Queries General Information
 
-**IMPORTANT**:
-
-1. **Mutation Types**: The GraphQL engine supports `Create`, `Update` and `Delete` operations
-2. **Id Based Mutations**: `Update` and `Delete` operations operate on Id-based entity identification
-3. **Mutation Schema**: Defined in the [mutation query schema](#mutation-query-schema) section
+The GraphQL engine supports `Create`, `Update`, and `Delete` operations. `Update` and `Delete` operate on Id-based entity identification. See the [mutation query schema](#mutation-query-schema) section.
 
 ## Mutation Query Generation Workflow
 
 Strictly follow the rules below when generating the GraphQL mutation query:
 
-1. **Input Fields Validation** - Validate that the set of fields validate [input field constraints](#mutation-queries-input-field-constraints)
+1. **Input Fields Validation** - Validate that the set of fields validate [input field constraints](#mutation-queries-input-field-constraints). Verify every field name and type against grep output from the schema — do NOT guess or assume
 2. **Output Fields Validation** - Validate that the set of fields used in the select part of the query validate the [output fields constraints](#mutation-queries-output-field-constraints)
-3. **Type Consistency** - Make sure variables used as query arguments and their related fields share the same GraphQL type
+3. **Type Consistency** - Make sure variables used as query arguments and their related fields share the same GraphQL type. Verify types via grep lookup — do NOT assume types
 4. **Report Phase** - Use the [Mutation Query Report Template](#mutation-query-report-template) below to report on the previous validation phases
 5. **Input Arguments** - `input` is the default name for the argument, unless otherwise specified
 6. **Output Field** - For `Create` and `Update` operations, the output field is always named `Record`, and is of type EntityName
-7. **Query Generation** - Use the [mutation query](#mutation-query-templates) template and adjust it based on the selected operation
-8. **Output Format** - Use the [standalone](#mutation-standalone-default-output-format---clean-code-only)
-9. **Test the Query** - Use the [Generated Mutation Query Testing](#generated-mutation-query-testing) workflow to test the generated query
-   1. **Report First** - Always report first, using the proper output format, before testing
+7. **Field Name Validation** - Every field name in the generated mutation **MUST** match a field confirmed via grep lookup in the schema. Do NOT guess or assume field names exist
+8. **Query Generation** - Use the [mutation query](#mutation-query-templates) template and adjust it based on the selected operation
+9. **Output Format** - Use the [standalone](#mutation-standalone-default-output-format---clean-code-only)
+10. **Lint Validation** - After writing the mutation to a file, run `npx eslint <file>` from the webapp dir to validate it against the schema. Fix any reported errors before proceeding. See [Lint Validation](#lint-validation) for details
+11. **Test the Query** - Use the [Generated Mutation Query Testing](#generated-mutation-query-testing) workflow to test the generated query
+    1. **Report First** - Always output the generated mutation in the proper output format BEFORE initiating any test
 
 ## Mutation Query Schema
 
@@ -127,7 +134,7 @@ mutation mutateEntityName(
 ## Mutation Standalone (Default) Output Format - CLEAN CODE ONLY
 
 ```javascript
-import { gql } from 'api/graphql.ts';
+import { gql } from '@salesforce/sdk-data';
 const QUERY_NAME = gql`
   mutation mutateEntity($input: EntityNameOperationInput!) {
     uiapi {
@@ -150,36 +157,54 @@ const QUERY_VARIABLES = {
 };
 ```
 
-**❌ DO NOT INCLUDE:**
+**❌ FORBIDDEN — Do NOT include any of the following:**
 
-- Explanatory comments about the query
-- Field descriptions
+- Explanatory comments about the query (inline or surrounding)
+- Field descriptions or annotations
 - Additional text about what the query does
-- Workflow step descriptions
+- Workflow step descriptions or summaries
+- Comments like `// fetches...`, `// creates...`, `/* ... */`
 
-**✅ ONLY INCLUDE:**
+**✅ ONLY output:**
 
-- Raw query string
-- Variables object
-- Nothing else
+- The raw query string constant (using `gql` tagged template)
+- The variables object constant
+- Nothing else — no extra imports, no exports, no wrapper functions
+
+## Lint Validation
+
+After writing the generated mutation into a source file, validate it against the schema using the project's GraphQL ESLint setup:
+
+```bash
+# Run from webapp dir (force-app/main/default/webapplications/<app-name>/)
+npx eslint <path-to-file-containing-mutation>
+```
+
+**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 (invoke `salesforce-graphql-explore-schema` first) and project dependencies must be installed (`npm install`).
 
 ## Generated Mutation Query Testing
 
-**Triggering conditions** - **ALL CONDITIONS MUST VALIDATE\***
+**Triggering conditions** — **ALL conditions must be true:**
 
-1. Only if the [Mutation Query Generation Workflow](#mutation-query-generation-workflow) step global status is `SUCCESS` and you have a generated query
-2. Only if the query to generate is a mutation query
-3. Only if non manual method was used during schema exploration to retrieve introspection data
+1. The [Mutation Query Generation Workflow](#mutation-query-generation-workflow) completed with status `SUCCESS` and you have a generated query
+2. The query is a mutation query
+3. A non-manual method was used during schema exploration to retrieve introspection data
 
 **Workflow**
 
-1. **Report Step** - Explain that you are able to test the query using `sf api request rest`
-2. **Interactive Step** - Ask the user whether they want you to test the query
-   1. **WAIT** for the user's answer.
-3. **Input Arguments** - You **MUST** ask the user for the input arguments to use
-   1. **WAIT** for the user's answer.
-4. **Test Query** - If the user are OK with you testing the query:
-   1. Use `sf api request rest` to POST the query and variables to the GraphQL endpoint:
+1. **Report Step** - State the exact method you will use to test (e.g., `sf api request graphql` from the **project root**, Connect API, etc.) — this **MUST** match the method used during schema exploration
+2. **Interactive Step** - Ask the user whether they want you to test the query using the proposed method
+   1. **STOP and WAIT** for the user's answer. Do NOT proceed until the user responds. Do NOT assume consent.
+3. **Input Arguments** - You **MUST** ask the user for the input argument values to use in the test
+   1. **STOP and WAIT** for the user's answer. Do NOT proceed until the user provides values. Do NOT fabricate test data.
+4. **Test Query** - Only if the user explicitly agrees and has provided input values:
+   1. Execute the mutation using the reported method (e.g., `sf api request rest` to POST the query and variables to the GraphQL endpoint):
       ```bash
       sf api request rest /services/data/v65.0/graphql \
         --method POST \
@@ -207,14 +232,14 @@ The query is invalid:
    - **Navigation** - Error contains `is not currently available in mutation results`
    - **API Version** - Query deals with updates, you're testing with Connect API and error contains `Cannot invoke JsonElement.isJsonObject()`
 3. **Targeted Resolution** - Depending on the root cause categorization
-   - **Execution** - You're trying to update or delete an unknown/no longer available entity: either create an entity first, if you have generated the related query, or ask for a valid entity id to use
+   - **Execution** - You're trying to update or delete an unknown/no longer available entity: either create an entity first, if you have generated the related query, or ask for a valid entity id to use. **STOP and WAIT** for the user to provide a valid Id
    - **Syntax** - Update the query using the error message information to fix the syntax errors
-   - **Validation** - This field's name is most probably invalid, ask user for clarification and **WAIT** for the user's answer
-   - **Type** - Use the error details and GraphQL schema to correct argument's type, and adjust variables accordingly
+   - **Validation** - The field name is most probably invalid. Re-run the relevant grep command from the `salesforce-graphql-explore-schema` skill to verify the correct field name. If still unclear, ask the user for clarification and **STOP and WAIT** for their answer
+   - **Type** - Use the error details and re-verify the type via grep lookup in the schema. Correct the argument type and adjust variables accordingly
    - **Navigation** - Use the [`PARTIAL` status handling workflow](#partial-status-handling-workflow) below
    - **API Version** - `Record` selection is only available with API version 64 and higher, **report** the issue, and try again with API version 64
 4. **Test Again** - Resume the [query testing workflow](#generated-mutation-query-testing) with the updated query (increment and track attempt counter)
-5. **Escalation Path** - If targeted resolution fails after 2 attempts, ask for additional details and restart the entire GraphQL workflow, going again through the introspection phase
+5. **Escalation Path** - If targeted resolution fails after 2 attempts, ask for additional details and restart the entire GraphQL workflow from the `salesforce-graphql-explore-schema` skill
 
 ### `PARTIAL` Status Handling Workflow
 
@@ -224,5 +249,10 @@ The query can be improved:
 2. Explain that these fields can't be queried as part of a mutation query
 3. Explain that the query might be considered as failing, as it will report errors
 4. Offer to remove the offending fields
-5. **WAIT** for the user's answer
+5. **STOP and WAIT** for the user's answer. Do NOT remove fields without explicit consent.
 6. If they are OK with removing the fields restart the [generation workflow](#mutation-query-generation-workflow) with the new field list
+
+## Related Skills
+
+- Schema exploration: `salesforce-graphql-explore-schema` (must complete first)
+- Read query generation: `salesforce-graphql-read-query`