@salesforce/webapp-template-feature-react-file-upload-experimental 1.105.1 → 1.106.0

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

@@ -0,0 +1,165 @@
+---
+name: salesforce-data-access
+description: Salesforce data access patterns. Use when adding or modifying any code that fetches data from Salesforce (records, Chatter, Connect API, etc.).
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.graphql"
+---
+
+# Salesforce Data Access
+
+Guidance for accessing Salesforce data from web apps. **All Salesforce data fetches MUST use the Data SDK** (`@salesforce/sdk-data`). The SDK provides authentication, CSRF handling, and correct base URL resolution — direct `fetch` or `axios` calls bypass these and are not allowed.
+
+## Mandatory: Use the Data SDK
+
+> **Every Salesforce data fetch must go through the Data SDK.** Obtain it via `createDataSDK()`, then use `sdk.graphql?.()` or `sdk.fetch?.()`. Never call `fetch()` or `axios` directly for Salesforce endpoints.
+
+## Optional Chaining and Graceful Handling
+
+**Always use optional chaining** when calling `sdk.graphql` or `sdk.fetch` — these methods may be undefined in some surfaces (e.g., Salesforce ACC, MCP Apps). Handle the case where they are not available gracefully:
+
+```typescript
+const sdk = await createDataSDK();
+
+// ✅ Use optional chaining
+const response = await sdk.graphql?.(query);
+
+// ✅ Check before using fetch
+if (!sdk.fetch) {
+  throw new Error("Data SDK fetch is not available in this context");
+}
+const res = await sdk.fetch(url);
+```
+
+For GraphQL, if `sdk.graphql` is undefined, the call returns `undefined` — handle that in your logic (e.g., throw a clear error or return a fallback). For `sdk.fetch`, check availability before calling when the operation is required.
+
+## Preference: GraphQL First
+
+**GraphQL is the preferred method** for querying and mutating Salesforce records. Use it when:
+
+- Querying records (Account, Contact, Opportunity, custom objects)
+- Creating, updating, or deleting records (when GraphQL supports the operation)
+- Fetching related data, filters, sorting, pagination
+
+**Use `sdk.fetch` only when GraphQL is not sufficient.** For REST API usage, invoke the `salesforce-rest-api-fetch` skill, which documents:
+
+- Chatter API (e.g., `/services/data/v65.0/chatter/users/me`)
+- Connect REST API (e.g., `/services/data/v65.0/connect/file/upload/config`)
+- Apex REST (e.g., `/services/apexrest/auth/login`)
+- UI API REST (e.g., `/services/data/v65.0/ui-api/records/{recordId}`)
+- Einstein LLM Gateway
+
+---
+
+## Getting the SDK
+
+```typescript
+import { createDataSDK } from "@salesforce/sdk-data";
+
+const sdk = await createDataSDK();
+```
+
+---
+
+## Example 1: GraphQL (Preferred)
+
+For record queries and mutations, use GraphQL via the Data SDK. Invoke the `salesforce-graphql` skill for the full workflow (schema exploration, query authoring, codegen, lint validate).
+
+```typescript
+import { createDataSDK, gql } from "@salesforce/sdk-data";
+import type { GetAccountsQuery } from "../graphql-operations-types";
+
+const GET_ACCOUNTS = gql`
+  query GetAccounts {
+    uiapi {
+      query {
+        Account(first: 10) {
+          edges {
+            node {
+              Id
+              Name { value }
+            }
+          }
+        }
+      }
+    }
+  }
+`;
+
+export async function getAccounts() {
+  const sdk = await createDataSDK();
+  const response = await sdk.graphql?.<GetAccountsQuery>(GET_ACCOUNTS);
+
+  if (response?.errors?.length) {
+    throw new Error(response.errors.map((e) => e.message).join("; "));
+  }
+
+  return response?.data?.uiapi?.query?.Account?.edges?.map((e) => e?.node) ?? [];
+}
+```
+
+---
+
+## Example 2: Fetch (When GraphQL Is Not Sufficient)
+
+For REST endpoints that have no GraphQL equivalent, use `sdk.fetch`. **Invoke the `salesforce-rest-api-fetch` skill** for full documentation of Chatter, Connect REST, Apex REST, UI API REST, and Einstein LLM endpoints.
+
+```typescript
+import { createDataSDK } from "@salesforce/sdk-data";
+
+declare const __SF_API_VERSION__: string;
+const API_VERSION = typeof __SF_API_VERSION__ !== "undefined" ? __SF_API_VERSION__ : "65.0";
+
+export async function getCurrentUser() {
+  const sdk = await createDataSDK();
+  const response = await sdk.fetch?.(`/services/data/v${API_VERSION}/chatter/users/me`);
+
+  if (!response?.ok) throw new Error(`HTTP ${response?.status}`);
+  const data = await response.json();
+  return { id: data.id, name: data.name };
+}
+```
+
+---
+
+## Anti-Patterns (Forbidden)
+
+### Direct fetch to Salesforce
+
+```typescript
+// ❌ FORBIDDEN — bypasses Data SDK auth and CSRF
+const res = await fetch("/services/data/v65.0/chatter/users/me");
+```
+
+### Direct axios to Salesforce
+
+```typescript
+// ❌ FORBIDDEN — bypasses Data SDK
+const res = await axios.get("/services/data/v65.0/chatter/users/me");
+```
+
+### Correct approach
+
+```typescript
+// ✅ CORRECT — use Data SDK
+const sdk = await createDataSDK();
+const res = await sdk.fetch?.("/services/data/v65.0/chatter/users/me");
+```
+
+---
+
+## Decision Flow
+
+1. **Need to query or mutate Salesforce records?** → Use GraphQL via the Data SDK. Invoke the `salesforce-graphql` skill.
+2. **Need Chatter, Connect REST, Apex REST, UI API REST, or Einstein LLM?** → Use `sdk.fetch`. Invoke the `salesforce-rest-api-fetch` skill.
+3. **Never** use `fetch`, `axios`, or similar directly for Salesforce API calls.
+
+---
+
+## Reference
+
+- GraphQL workflow: invoke the `salesforce-graphql` skill (`.a4drules/skills/salesforce-graphql/`)
+- REST API via fetch: invoke the `salesforce-rest-api-fetch` skill (`.a4drules/skills/salesforce-rest-api-fetch/`)
+- Data SDK package: `@salesforce/sdk-data` (`createDataSDK`, `gql`, `NodeOfConnection`)
+- `createRecord` for UI API record creation: `@salesforce/webapp-experimental/api` (uses Data SDK internally)

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