@salesforce/webapp-template-feature-react-file-upload-experimental 1.55.0

package/LICENSE.txt

@@ -0,0 +1,82 @@
+Terms of Use
+
+Copyright 2026 Salesforce, Inc. All rights reserved.
+
+These Terms of Use govern the download, installation, and/or use of this
+software provided by Salesforce, Inc. ("Salesforce") (the "Software"), were
+last updated on April 15, 2025, and constitute a legally binding
+agreement between you and Salesforce. If you do not agree to these Terms of
+Use, do not install or use the Software.
+
+Salesforce grants you a worldwide, non-exclusive, no-charge, royalty-free
+copyright license to reproduce, prepare derivative works of, publicly
+display, publicly perform, sublicense, and distribute the Software and
+derivative works subject to these Terms. These Terms shall be included in
+all copies or substantial portions of the Software.
+
+Subject to the limited rights expressly granted hereunder, Salesforce
+reserves all rights, title, and interest in and to all intellectual
+property subsisting in the Software. No rights are granted to you hereunder
+other than as expressly set forth herein. Users residing in countries on
+the United States Office of Foreign Assets Control sanction list, or which
+are otherwise subject to a US export embargo, may not use the Software.
+
+Implementation of the Software may require development work, for which you
+are responsible. The Software may contain bugs, errors and
+incompatibilities and is made available on an AS IS basis without support,
+updates, or service level commitments.
+
+Salesforce reserves the right at any time to modify, suspend, or
+discontinue, the Software (or any part thereof) with or without notice. You
+agree that Salesforce shall not be liable to you or to any third party for
+any modification, suspension, or discontinuance.
+
+You agree to defend Salesforce against any claim, demand, suit or
+proceeding made or brought against Salesforce by a third party arising out
+of or accruing from (a) your use of the Software, and (b) any application
+you develop with the Software that infringes any copyright, trademark,
+trade secret, trade dress, patent, or other intellectual property right of
+any person or defames any person or violates their rights of publicity or
+privacy (each a "Claim Against Salesforce"), and will indemnify Salesforce
+from any damages, attorney fees, and costs finally awarded against
+Salesforce as a result of, or for any amounts paid by Salesforce under a
+settlement approved by you in writing of, a Claim Against Salesforce,
+provided Salesforce (x) promptly gives you written notice of the Claim
+Against Salesforce, (y) gives you sole control of the defense and
+settlement of the Claim Against Salesforce (except that you may not settle
+any Claim Against Salesforce unless it unconditionally releases Salesforce
+of all liability), and (z) gives you all reasonable assistance, at your
+expense.
+
+WITHOUT LIMITING THE GENERALITY OF THE FOREGOING, THE SOFTWARE IS NOT
+SUPPORTED AND IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IN NO EVENT SHALL SALESFORCE HAVE ANY LIABILITY FOR ANY DAMAGES,
+INCLUDING, BUT NOT LIMITED TO, DIRECT, INDIRECT, SPECIAL, INCIDENTAL,
+PUNITIVE, OR CONSEQUENTIAL DAMAGES, OR DAMAGES BASED ON LOST PROFITS, DATA,
+OR USE, IN CONNECTION WITH THE SOFTWARE, HOWEVER CAUSED AND WHETHER IN
+CONTRACT, TORT, OR UNDER ANY OTHER THEORY OF LIABILITY, WHETHER OR NOT YOU
+HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+These Terms of Use shall be governed exclusively by the internal laws of
+the State of California, without regard to its conflicts of laws
+rules. Each party hereby consents to the exclusive jurisdiction of the
+state and federal courts located in San Francisco County, California to
+adjudicate any dispute arising out of or relating to these Terms of Use and
+the download, installation, and/or use of the Software. Except as expressly
+stated herein, these Terms of Use constitute the entire agreement between
+the parties, and supersede all prior and contemporaneous agreements,
+proposals, or representations, written or oral, concerning their subject
+matter. No modification, amendment, or waiver of any provision of these
+Terms of Use shall be effective unless it is by an update to these Terms of
+Use that Salesforce makes available, or is in writing and signed by the
+party against whom the modification, amendment, or waiver is to be
+asserted.
+
+Data Privacy: Salesforce may collect, process, and store device,
+system, and other information related to your use of the Software. This
+information includes, but is not limited to, IP address, user metrics, and
+other data ("Usage Data"). Salesforce may use Usage Data for analytics,
+product development, and marketing purposes. You acknowledge that files
+generated in conjunction with the Software may contain sensitive or
+confidential data, and you are solely responsible for anonymizing and
+protecting such data.

package/README.md

@@ -0,0 +1,102 @@
+# Feature: File Upload
+
+File upload feature: use the **FileUpload** component as-is with out-of-the-box UI, or build a **custom UI** with the `useFileUpload` hook (custom trigger, drop zone, or both).
+
+## Usage
+
+### Option 1: FileUpload component (OOTB UI)
+
+Use the component as-is for a ready-made drop zone, dialog, and progress display.
+
+```tsx
+import { FileUpload } from "@salesforce/webapp-template-feature-react-file-upload-experimental";
+
+<FileUpload
+  multiple
+  accept="image/*,.pdf"
+  onUploadComplete={(files) => console.log("Uploaded:", files)}
+/>;
+```
+
+### Option 2: Custom UI with your own trigger
+
+Use the `useFileUpload` hook to control when the file picker opens. Render a hidden input and your own button or action.
+
+```tsx
+import {
+  useFileUpload,
+  type UseFileUploadOptions,
+} from "@salesforce/webapp-template-feature-react-file-upload-experimental";
+
+function CustomUploadButton() {
+  const { getInputProps, openFilePicker } = useFileUpload({
+    multiple: true,
+    onUploadComplete: (files) => console.log("Uploaded:", files),
+  });
+
+  return (
+    <>
+      <input {...getInputProps()} style={{ display: "none" }} />
+      <button type="button" onClick={openFilePicker}>
+        Upload files
+      </button>
+    </>
+  );
+}
+```
+
+### Option 3: Custom UI with drop zone and progress
+
+Build a custom drop zone and inline progress list (no dialog) using `getDropZoneProps` and `fileItems`:
+
+```tsx
+import { useFileUpload } from "@salesforce/webapp-template-feature-react-file-upload-experimental";
+
+function MyUpload() {
+  const { fileItems, getInputProps, getDropZoneProps, reset } = useFileUpload({
+    multiple: true,
+    onUploadComplete: (files) => console.log("Uploaded files:", files),
+  });
+
+  const input = getInputProps();
+  const drop = getDropZoneProps();
+
+  return (
+    <div>
+      <div {...drop}>
+        <input {...input} style={{ display: "none" }} />
+        Drop files here
+      </div>
+      {fileItems.map((item) => (
+        <div key={item.file.name}>
+          {item.file.name}: {item.state} {item.progress}%
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Exports
+
+- **FileUpload** – Component with OOTB drop zone, dialog, and progress. Props: `accept?`, `multiple?`, `recordId?`, `onUploadComplete?`, `onUploadError?`, `className?`.
+- **useFileUpload** – Headless hook for custom UIs. Returns `getInputProps`, `openFilePicker`, `fileItems`, `getDropZoneProps`, `cancelFile`, `reset`, etc.
+- **UseFileUploadOptions** – Type for the `useFileUpload` options.
+
+## Dependencies
+
+This feature depends on:
+
+- **feature-react-shadcn** – For UI components (Button, Dialog, etc.)
+- **@salesforce/webapp-experimental** – For API client and Salesforce integration
+
+## Build & Testing
+
+You can test the extension of the base app and the components via the following:
+
+```bash
+npm run build
+npm run start
+```
+
+Open the app and use the Home page to test the FileUpload component.

package/dist/.a4drules/README.md

@@ -0,0 +1,35 @@
+# A4D Rules Index
+
+Rules in this folder guide the agent for this SFDX project. **Knowledge** (expert content) lives in the **local-expert MCP** repo (e.g. `local-expert-mcp`); rules here reference when to call which expert.
+
+## Always-apply rules (MUST follow)
+
+| File | Purpose |
+|------|--------|
+| **webapp.md** | Main web app rules: invoke local-expert MCP (`webapplications-design-system` + `webapplications`), no `node -e`, React/SFDX workflow; **replace default boilerplate**; **populate home page**; **frontend aesthetics**—avoid AI slop, follow design-system expert. |
+| **webapp-no-node-e.md** | No `node -e` for any file/config/shell work; use `replace_in_file` or `write_to_file` only. |
+| **a4d-webapp-generate.md** | Before `sf webapp generate`: call `get_expert_knowledge` with `webapplications-design-system` and `webapplications`; then run CLI. |
+| **webapp-ui-first.md** | Build UI (layout, components, styling) first; then implement business logic (APIs, state, handlers). |
+| **webapp-nav-and-placeholders.md** | **Build navigation into the app layout** (`appLayout.tsx`). Always update nav menu (app-specific items/labels) and placeholder name/design (header/nav/footer/title). Often missed—mandatory. |
+
+## Context-specific rules (by file pattern or topic)
+
+| File | Purpose |
+|------|--------|
+| **react.md** | React web app structure, shadcn/Tailwind, data access, security; edit `appLayout.tsx` when changing layout. |
+| **ui-layout.md** | When changing UI/nav/header/footer/sidebar/theme, always update `appLayout.tsx`. |
+| **code-quality.md** | ESLint, Prettier, import order, naming, lint/build before completion; no `node -e`. |
+| **build-validation.md** | `npm run build` must succeed from web app dir before completing. |
+| **typescript.md** | TypeScript strictness, return types, interfaces. |
+| **images.md** | Images: Unsplash default, CSP, alt text, error handling. |
+| **react_image_processing.md** | Image handling (Unsplash, CSP, accessibility) for React components. |
+| **graphql/** | GraphQL tools and knowledge (schemas, LDS guides). |
+
+## Knowledge repository (experts)
+
+Expert knowledge is served by the **local-expert MCP** (e.g. at `local-expert-mcp`). The agent must call **`get_expert_knowledge`** with the appropriate topic:
+
+- **webapplications-design-system** — Always use for web app UI/design work (design system, typography, color, motion).
+- **webapplications** — Use for app generation and structure; then call sub-topics as needed (e.g. `webapplications-best-practice`, `webapplications-feature-*`).
+
+See the MCP repo's **rule-expert-mcp.md** for full topic list and when to call which expert.

package/dist/.a4drules/a4d-webapp-generate.md

@@ -0,0 +1,27 @@
+---
+description: A4D rule — call expert MCP (webapplications + webapplications-design-system) before sf webapp generate
+alwaysApply: true
+---
+
+# A4D Rule: Before `sf webapp generate`
+
+Before running **`sf webapp generate`**, you **must**:
+
+1. **Call the expert MCP** (`get_expert_knowledge`) with topic **`webapplications-design-system`** — always invoke this expert for UI/design direction.
+2. **Call the expert MCP** with topic **`webapplications`** to get generation and structure guidance.
+3. Follow the instructions from the MCP responses.
+4. Only after that, run `sf webapp generate` (e.g. `sf webapp generate -n <AppName> -t <template>`).
+
+**Webapp name (`-n` / `<AppName>`):** Must be **alphanumerical only**—no spaces, hyphens, underscores, or other special characters. Use only letters (A–Z, a–z) and digits (0–9). If the desired name has spaces or special characters, use a single alphanumeric word (e.g. `CoffeeBoutique` instead of `Coffee Boutique` or `coffee-boutique`).
+
+Do not run `sf webapp generate` without having invoked the expert MCP with **`webapplications-design-system`** and **`webapplications`** first.
+
+When modifying an existing web app (UI, layout, or new features), **always** call `get_expert_knowledge` with topic **`webapplications-design-system`** before making UI or design changes.
+
+**After generating (or when touching a new app):** Replace all default boilerplate content (e.g. "React App", "Vite + React", default document title in `index.html`, placeholder text in the shell) with the actual app name or user-facing copy. Do not leave generic template text in the UI or `<title>`.
+
+**Home page content:** Populate the home page (root route) with real, app-specific content (e.g. landing section, banners, tiles, hero, links to features). Never leave the home page as the default template or placeholder.
+
+**Navigation menu and placeholder name/design:** After generating or when delivering a web app, **you must** (1) **Edit the navigation menu** in `appLayout.tsx`: replace every default nav item and label with app-specific routes and names; do not leave template "Home"/"About" or placeholder links. (2) **Replace the placeholder app name** in the header, nav brand, footer, and `index.html` `<title>` with the actual app name. (3) **Update placeholder design** in the shell (header/footer/branding) so it is not the template default. See **webapp-nav-and-placeholders.md**. Agents often skip this—do not.
+
+Prioritize webapplications generation first, and then generate the metadata.

package/dist/.a4drules/build-validation.md

@@ -0,0 +1,78 @@
+# AI Rule: Build Validation
+
+Build validation for successful deployments with minimal friction.
+
+## Targets
+- `force-app/main/default/webapplications/*/**/*`
+- `**/*.{js,ts,jsx,tsx}`
+
+## MANDATORY: Build Success
+
+**Before completing any coding session** (from the web app directory `force-app/main/default/webapplications/<appName>/`):
+```bash
+npm run build  # MUST succeed with no errors
+```
+
+## Quick Quality Checks
+Run from the web app directory (`force-app/main/default/webapplications/<appName>/`):
+```bash
+npm run lint   # ESLint; fix issues before completing
+npm run build  # Runs tsc -b && vite build; catches TypeScript and build issues
+```
+
+## Requirements
+
+**Must Pass:**
+- `npm run build` completes successfully
+- No TypeScript compilation errors
+- No critical ESLint errors
+
+**Can Be Warnings:**
+- ESLint warnings
+- Minor TypeScript warnings
+
+## Fix Commands (when available in the web app's package.json)
+```bash
+npm run lint         # Run ESLint (always available)
+# If your project adds Prettier/format scripts, use those before completing
+```
+
+## Workflow
+
+**During Development:**
+1. Write code with AI assistance
+2. Save frequently (auto-format on save)
+3. Check periodically: `npm run lint` (optional)
+
+**Before Completion:**
+1. Run `npm run build` from the web app directory
+2. If it fails: fix TypeScript/ESLint errors (run `npm run lint`), then retry build
+
+## Error Priority
+
+**Fix Immediately:**
+- TypeScript compilation errors
+- Import/export errors
+- Syntax errors
+
+**Fix When Convenient:**
+- ESLint warnings
+- Unused variables
+
+## Hard Requirements
+- Build must complete without errors
+- No broken imports
+- Basic TypeScript type safety
+
+## Key Commands (web app directory)
+```bash
+npm run dev          # Start development server (vite)
+npm run build        # TypeScript + Vite build; check deployment readiness
+npm run lint         # Run ESLint
+```
+
+## Troubleshooting Import Errors
+```bash
+npm install          # Check missing dependencies
+# Verify file exists, case sensitivity, export/import match
+```

package/dist/.a4drules/code-quality.md

@@ -0,0 +1,137 @@
+# AI Rule: Code Quality Standards
+
+Enforces ESLint, Prettier, and coding best practices for consistent, maintainable code.
+
+**Execution rule:** Do not use `node -e` for any file or config edits. Use `replace_in_file` or `write_to_file` only (see **webapp-no-node-e.md**).
+
+## Targets
+- `force-app/main/default/webapplications/*/**/*`
+- `**/*.{js,ts,jsx,tsx,json,md}`
+
+## MANDATORY Checks
+
+**Before completing code** (run from the web app directory `force-app/main/default/webapplications/<appName>/`):
+```bash
+npm run lint   # MUST result in: 0 errors (0 warnings preferred)
+npm run build  # MUST succeed (includes TypeScript check)
+```
+
+If your project adds Prettier, use a consistent config (e.g. `.prettierrc` with `semi`, `singleQuote`, `printWidth`, etc.) and run format checks before completing.
+
+## Lint / Fix
+
+```bash
+npm run lint   # Run ESLint (always available in the template web app)
+# Use your editor's format-on-save or add npm scripts for Prettier if desired
+```
+
+## Import Order (MANDATORY)
+```typescript
+// 1. React ecosystem
+import { useState, useEffect } from 'react';
+
+// 2. External libraries (alphabetical)
+import axios from 'axios';
+import clsx from 'clsx';
+
+// 3. UI components (alphabetical)
+import { Button } from '@/components/ui/button';
+import { Card } from '@/components/ui/card';
+
+// 4. Internal utilities (alphabetical)
+import { useAuth } from '../hooks/useAuth';
+import { formatDate } from '../utils/dateUtils';
+
+// 5. Relative imports
+import { ComponentA } from './ComponentA';
+
+// 6. Type imports (separate, at end)
+import type { User, ApiResponse } from '../types';
+```
+
+## Naming Conventions
+```typescript
+// PascalCase: Components, classes
+const UserProfile = () => {};
+const ApiClient = class {};
+
+// camelCase: Variables, functions, properties
+const userName = 'john';
+const fetchUserData = async () => {};
+
+// SCREAMING_SNAKE_CASE: Constants
+const API_BASE_URL = 'https://api.example.com';
+
+// kebab-case: Files
+// user-profile.tsx, api-client.ts
+```
+
+## React Component Structure
+```typescript
+interface ComponentProps {
+  // Props interface first
+}
+
+const Component: React.FC<ComponentProps> = ({ prop1, prop2 }) => {
+  // 1. Hooks
+  // 2. Computed values
+  // 3. Event handlers
+  // 4. JSX return
+
+  return <div />;
+};
+
+export default Component;
+```
+
+## JSX Standards
+```typescript
+// Self-closing tags
+<Button onClick={handleClick} />
+
+// Conditional rendering
+{isLoading && <Spinner />}
+{error ? <ErrorMessage error={error} /> : <Content />}
+
+// Lists with keys
+{items.map(item => <Item key={item.id} data={item} />)}
+```
+
+## Error Handling
+```typescript
+// Async functions with try-catch
+const fetchData = async (id: string): Promise<Data> => {
+  try {
+    const response = await api.get(`/data/${id}`);
+    return response.data;
+  } catch (error) {
+    console.error('Failed to fetch data:', error);
+    throw error;
+  }
+};
+```
+
+## Anti-Patterns (FORBIDDEN)
+```typescript
+// NEVER disable ESLint without justification
+// eslint-disable-next-line
+
+// NEVER mutate state directly
+state.items.push(newItem); // Wrong
+setItems(prev => [...prev, newItem]); // Correct
+
+// NEVER use magic numbers/strings
+setTimeout(() => {}, 5000); // Wrong
+const DEBOUNCE_DELAY = 5000; // Correct
+```
+
+## Quality Workflow
+
+**Before Committing:**
+1. `npm run lint` - 0 errors (and 0 warnings when possible)
+2. `npm run build` - Build must succeed (TypeScript + Vite)
+
+## Zero Tolerance Policy
+- ESLint errors: MUST be 0
+- ESLint warnings: MUST be 0 (fix when convenient)
+- TypeScript errors: MUST be 0 (enforced by `npm run build`)

package/dist/.a4drules/graphql/tools/knowledge/lds-explore-graphql-schema.md

@@ -0,0 +1,227 @@
+# GraphQL Schema Reference
+
+This document provides guidance for AI agents working with the Salesforce GraphQL API schema in this project.
+
+## Schema File Location
+
+**The complete GraphQL schema is located at: `@schema.graphql`** (in the project root)
+
+> ⚠️ **Important**: The schema file is very large (~265,000+ lines). Do NOT read it entirely. Instead, use targeted searches to find specific types, fields, or operations.
+
+If the file is not present, generate it by running:
+```bash
+npm run graphql:get-schema
+```
+
+## Required Pre-Flight Check
+
+**BEFORE generating any GraphQL query, you MUST:**
+
+1. **Check if schema exists**: Look for `schema.graphql` in the project root
+2. **If schema is missing**: 
+   - Run `npm run graphql:get-schema` to download it
+   - Wait for the command to complete successfully
+   - Then proceed with schema exploration
+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
+
+The schema follows the Salesforce GraphQL Wire Adapter pattern with these main entry points:
+
+### Query Entry Point
+```graphql
+type Query {
+  uiapi: UIAPI!
+}
+```
+
+### UIAPI Structure
+```graphql
+type UIAPI {
+  query: RecordQuery!           # For querying records
+  aggregate: RecordQueryAggregate!  # For aggregate queries
+  objectInfos: [ObjectInfo]     # For metadata
+  relatedListByName: RelatedListInfo
+}
+```
+
+### Mutation Entry Point
+```graphql
+type Mutation {
+  uiapi(input: UIAPIMutationsInput): UIAPIMutations!
+}
+```
+
+## How to Explore the Schema
+
+When you need to build a GraphQL query, use these search patterns:
+
+### 1. Find Available Fields for a Record Type
+Search for `type <ObjectName> implements Record` to find all queryable fields:
+```bash
+# Example: Find Account fields
+grep "^type Account implements Record" schema.graphql -A 50
+```
+
+### 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
+grep "^input Account_Filter" schema.graphql -A 30
+```
+
+### 3. Find OrderBy Options
+Search for `input <ObjectName>_OrderBy` for sorting options:
+```bash
+# Example: Find Account ordering options
+grep "^input Account_OrderBy" schema.graphql -A 20
+```
+
+### 4. Find Mutation Operations
+Search for operations in `UIAPIMutations`:
+```bash
+# Example: Find Account mutations
+grep "Account.*Create\|Account.*Update\|Account.*Delete" schema.graphql
+```
+
+### 5. Find Input Types for Mutations
+Search for `input <ObjectName>CreateInput` or `input <ObjectName>UpdateInput`:
+```bash
+# Example: Find Account create input
+grep "^input AccountCreateInput" schema.graphql -A 30
+```
+
+## Common Operator Types
+
+### StringOperators (for text fields)
+```graphql
+input StringOperators {
+  eq: String      # equals
+  ne: String      # not equals
+  like: String    # pattern matching (use % as wildcard)
+  lt: String      # less than
+  gt: String      # greater than
+  lte: String     # less than or equal
+  gte: String     # greater than or equal
+  in: [String]    # in list
+  nin: [String]   # not in list
+}
+```
+
+### OrderByClause
+```graphql
+input OrderByClause {
+  order: ResultOrder   # ASC or DESC
+  nulls: NullOrder     # FIRST or LAST
+}
+```
+
+## Query Pattern Examples
+
+### Basic Query Structure
+All record queries follow this pattern:
+```graphql
+query {
+  uiapi {
+    query {
+      <ObjectName>(
+        first: Int           # pagination limit
+        after: String        # pagination cursor
+        where: <Object>_Filter
+        orderBy: <Object>_OrderBy
+      ) {
+        edges {
+          node {
+            Id
+            <Field> { value }
+            # ... more fields
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Example: Query Accounts with Filter
+```graphql
+query GetHighRevenueAccounts($minRevenue: Currency) {
+  uiapi {
+    query {
+      Account(
+        where: { AnnualRevenue: { gt: $minRevenue } }
+        orderBy: { AnnualRevenue: { order: DESC } }
+        first: 50
+      ) {
+        edges {
+          node {
+            Id
+            Name { value }
+            AnnualRevenue { value }
+            Industry { value }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Mutation Pattern
+```graphql
+mutation CreateAccount($input: AccountCreateInput!) {
+  uiapi(input: { AccountCreate: { input: $input } }) {
+    AccountCreate {
+      Record {
+        Id
+        Name { value }
+      }
+    }
+  }
+}
+```
+
+## 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
+
+**Pre-requisites (MANDATORY):**
+- [ ] Verified `schema.graphql` exists in project root
+- [ ] If missing, ran `npm run graphql:get-schema` 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. **Search the schema** for the object type to discover available fields
+3. **Search for filter input** (`<Object>_Filter`) to understand filtering options
+4. **Search for orderBy input** (`<Object>_OrderBy`) for sorting capabilities
+5. **Build the query** following the patterns above
+6. **Validate field names** match exactly as defined in the schema (case-sensitive)
+
+## Tips for Agents
+
+- **Always verify field names** by searching the schema before generating queries
+- **Use grep/search** to explore the schema efficiently—never read the entire file
+- **Check relationships** by looking for `parentRelationship` and `childRelationship` comments in type definitions
+- **Look for Connection types** (e.g., `AccountConnection`) to understand pagination structure
+- **Custom objects** end with `__c` (e.g., `CustomObject__c`)
+- **Custom fields** also end with `__c` (e.g., `Custom_Field__c`)
+
+## Related Documentation
+
+- For generating mutations and queries, see `lds-generate-graphql-mutationquery.md`
+- For GraphQL best practices, see `lds-guide-graphql.md`