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

package/dist/.a4drules/react.md

@@ -0,0 +1,387 @@
+# AI Customization Rule: React Web App (SFDX)
+
+This rule consolidates React web application guidelines, data access rules, security standards, anti-patterns, and project integration requirements for consistent AI-generated code.
+
+## Targets (File Pattern Matching)
+
+Apply these rules to the React web app files under the SFDX package directory:
+
+- `force-app/main/default/webapplications/*/**/*.js`
+- `force-app/main/default/webapplications/*/**/*.jsx`
+- `force-app/main/default/webapplications/*/**/*.ts`
+- `force-app/main/default/webapplications/*/**/*.tsx`
+
+## Rule Objectives
+
+- Enforce secure, performant, and maintainable patterns for Salesforce data access.
+- Standardize UI with shadcn/ui and Tailwind.
+- Prevent prohibited patterns that break React or Salesforce constraints.
+
+## UI / layout edits (MANDATORY — read before any UI change)
+
+**When the user asks for UI changes** (new components, pages, navigation, header, footer, sidebar, theme, or “layout”):  
+**You MUST open and update `src/appLayout.tsx`** (the theme layout) whenever the change affects how the app shell looks or behaves.  
+Do not only edit pages or components and leave `appLayout.tsx` unchanged.  
+If in doubt, **edit appLayout.tsx as well**.  
+The layout file is: `force-app/main/default/webapplications/<appName>/src/appLayout.tsx` (or the app’s `appLayout.tsx` used by `routes.tsx`).
+
+**Navigation menu and placeholder name/design:** In `appLayout.tsx`, always replace the **default navigation menu** (items and labels) with app-specific links and names, and replace the **placeholder app name** (header, nav brand, footer) and **placeholder design** with the actual app name and intentional styling. Do not leave template nav or "React App"–style branding. See **webapp-nav-and-placeholders.md**.
+
+## Project & Entry Points
+
+- React web app root: `force-app/main/default/webapplications/<appName>/`
+- Main entry component: `force-app/main/default/webapplications/<appName>/src/App.tsx`
+- **Theme/layout shell**: `force-app/main/default/webapplications/<appName>/src/appLayout.tsx` — wraps all routed content (navigation, header, sidebar, outlet). Routes use `<AppLayout />` as the layout element; page content renders inside it via `<Outlet />`. When making UI edits that affect global layout, navigation, header, footer, sidebar, or theme, **you must consider and edit appLayout.tsx** in addition to page or component files; do not only edit individual pages and omit the layout.
+- Running Development Server (from the web app directory):
+  - `npm run dev` — starts the Vite dev server
+  - You can generally assume the dev server is already running and don't need to start it.
+- Build (from the web app directory):
+  - `npm run build` — TypeScript check + Vite build
+- Deploy and open in Salesforce are done from the **SFDX project root** (e.g. via Salesforce CLI or the IDE), not via the web app's package.json. Keep the app buildable so deploy workflows continue to work.
+
+## Component Library (MANDATORY)
+
+- Use shadcn/ui for UI components (Buttons, Cards, Inputs, Dialogs, etc.).
+- Import patterns:
+
+```javascript
+import { Button } from '@/components/ui/button';
+import { Card, CardHeader, CardContent } from '@/components/ui/card';
+import { Input } from '@/components/ui/input';
+```
+
+## Styling Standards
+
+- Use Tailwind CSS utility classes.
+- Follow consistent spacing, color, and typography conventions.
+
+## React & TypeScript Standards
+
+- Component Architecture: Prefer functional components with hooks.
+- File Naming: Use PascalCase for components (e.g., `Button.tsx`) and camelCase for hooks (e.g., `useAuth.ts`).
+- Imports: Use absolute paths (e.g., `@/components/...`) if the `tsconfig.json` or `vite.config.ts` supports it.
+- State: Default to `useState` for local state; avoid adding global state libraries unless requested.
+
+## Layout and theme (appLayout.tsx) — CRITICAL for UI edits
+
+- **appLayout.tsx** is the application shell: it wraps every page and typically contains the main navigation (e.g. `NavigationMenu`), header, sidebar, and `<Outlet />` for child routes. It defines the global look and structure of the app.
+- **MANDATORY:** When asked to change the UI in ways that affect the **overall layout**, **navigation**, **header**, **footer**, **sidebar**, or **theme** (e.g. add a top bar, change nav items, add a sidebar, apply a theme wrapper), you **MUST** edit `appLayout.tsx` (or the app’s layout file) as part of the same change. Do not only edit individual pages or components and leave the layout unchanged.
+- **Before finishing any UI edit:** Ask yourself: “Does this touch layout, nav, header, footer, sidebar, or theme?” If yes, **you must have modified appLayout.tsx** (or the layout file used by routes). If you did not, add that edit before considering the task done.
+- If the project uses feature inheritance (e.g. `__inherit__appLayout`), the editable layout may live in the app or feature at `src/appLayout.tsx`; ensure you modify the correct file that is actually used by `routes.tsx`.
+
+## Module & Platform Restrictions
+
+- React apps must NOT import or rely on Salesforce platform modules; do not use:
+  - `@salesforce/*`
+  - `lightning/*`
+  - `@wire` (LWC-only)
+- Use standard web APIs and npm packages only.
+
+## LWC MCP Server Integration (Data Access Guidance)
+
+The LWC MCP server (via Agentforce Vibes extension) provides framework-agnostic data access guidance for UI API and GraphQL patterns.
+
+### Primary Tool: `orchestrate_lds_data_requirements`
+
+The `orchestrate_lds_data_requirements` tool analyzes data requirements and routes to appropriate guidance tools (UI API or GraphQL). **Note:** Tool names may change, but the purpose remains orchestrating LDS data requirements.
+
+**Important for React Applications:** If the MCP tool recommends Apex REST, React applications should ignore this recommendation. Apex REST is not available in React applications. Follow the [Apex REST Strategy](#data-access-priority-order) section above to evaluate whether GraphQL can handle the requirement, or inform the user that the feature is not currently supported in React.
+
+### Tool Availability Check (MANDATORY)
+
+Before implementing data access, **MUST** verify `orchestrate_lds_data_requirements` is available. If unavailable:
+
+1. Notify user: "LWC MCP data access tools not enabled. Add 'lwc-experts' to --toolsets in a4d_mcp_settings.json"
+2. Offer to update the file if you have write access
+3. Otherwise, provide manual instructions
+
+**Configuration:** Add `"lwc-experts"` to `--toolsets` in `a4d_mcp_settings.json` (typically at `{VSCode/Cursor globalStorage}/salesforce.salesforcedx-einstein-gpt/settings/a4d_mcp_settings.json`). Example: `"metadata,lwc-experts"` in the args array.
+
+### LWC MCP Server Tool Usage Restrictions (CRITICAL)
+
+**This rule applies when building React applications. Do NOT create LWC components or use LWC-specific development tools.**
+
+**Allowed MCP Tools (Data Access Only):**
+
+- `orchestrate_lds_data_requirements` - Primary tool for data access guidance
+- Any data access guidance tools referenced by `orchestrate_lds_data_requirements` (e.g., UI API or GraphQL guidance tools)
+
+**Note:** If the MCP tool recommends Apex REST guidance tools, React applications should ignore these recommendations as Apex REST is not available in React.
+
+**Prohibited MCP Tools (LWC Component Development):**
+
+- `guide_lwc_development` - LWC component development guidance
+- `orchestrate_lwc_component_creation` - LWC component creation orchestration
+- `create_lwc_component_from_prd` - LWC component creation from PRD
+- Any other LWC component creation, development, or framework-specific tools
+
+**Enforcement:**
+
+- **NEVER** call LWC component creation or development tools from the LWC MCP server
+- **ONLY** use data access related tools that provide framework-agnostic guidance
+- If you encounter a request to create LWC components, remind the user that you are building a React app and redirect them to use React patterns instead
+
+## Data Access Rules (CRITICAL)
+
+- MANDATORY: Use `axios` for all API calls from React.
+
+### Data Access Workflow (MANDATORY)
+
+**Before implementing any data access functionality:**
+
+1. **Proactively check** for LWC MCP server tool availability (see [LWC MCP Server Integration](#lwc-mcp-server-integration-data-access-guidance) section above)
+2. **Use the LWC MCP server's `orchestrate_lds_data_requirements` tool** to get guidance on the appropriate data access pattern
+3. The MCP tool will analyze your requirements and guide you to the appropriate Salesforce data access pattern (GraphQL or UI API)
+4. **Follow the MCP tool's recommendations** when implementing data access code, prioritizing GraphQL for all operations
+5. **If the tool recommends Apex REST**, ignore this recommendation and follow the [Apex REST Strategy](#data-access-priority-order) to evaluate if GraphQL can handle the requirement
+
+**Note:** The code examples below serve as reference patterns, but your implementation should be informed by the MCP tool's guidance, which provides the most up-to-date best practices and framework-agnostic patterns.
+
+### Data Access Priority Order
+
+The LWC MCP server's `orchestrate_lds_data_requirements` tool follows this priority order when recommending data access patterns:
+
+1. **GraphQL** (queries & mutations) - Preferred for all data operations including reads, writes, complex queries, relationships, and multi-entity operations
+2. **Salesforce UI API** - For standard CRUD operations when GraphQL is not suitable
+
+**Apex REST Strategy (CRITICAL):**
+
+- **Apex REST is NOT available in React applications.** If the MCP tool recommends Apex REST, or if you believe Apex is needed:
+  1. **Reflect** on why Apex seems necessary
+  2. **Evaluate** whether GraphQL queries or mutations can accomplish the task
+  3. **If GraphQL cannot handle the requirement**, inform the user that the feature is not currently supported in React applications
+  4. **Do NOT** implement Apex REST endpoints or attempt to call them from React
+
+**Note:** For AI/generative features, see the [Einstein LLM Gateway](#einstein-llm-gateway-aigenerative-features) section below.
+
+### Reference Code Examples
+
+The following code examples serve as reference patterns for React applications. **Always consult the LWC MCP server's `orchestrate_lds_data_requirements` tool first** to ensure you're using the most appropriate pattern and latest best practices for your specific use case.
+
+UI API example (read):
+
+```javascript
+async function fetchRecord(recordId) {
+  try {
+    const res = await axios.get(
+      `/services/data/v62.0/ui-api/records/${recordId}`
+    );
+    return res.data;
+  } catch (error) {
+    const text = error.message;
+    throw new Error(`UI API failed: ${error.status} ${text}`);
+  }
+}
+```
+
+GraphQL utility (supports both queries and mutations):
+
+```javascript
+export async function sfGraphQL(query, variables = {}) {
+  try {
+    const res = await axios.post('/services/data/v62.0/graphql', {
+      query,
+      variables,
+    });
+    const json = res.data;
+    if (Array.isArray(json.errors) && json.errors.length) {
+      throw new Error(json.errors.map(e => e.message).join('; '));
+    }
+    return json.data;
+  } catch (error) {
+    throw new Error(`GraphQL error: ${error.status}`);
+  }
+}
+```
+
+GraphQL query example:
+
+```javascript
+const GET_ACCOUNT = `
+  query GetAccount($id: ID!) {
+    uiapi {
+      query {
+        Account(where: { Id: { eq: $id } }) {
+          edges {
+            node {
+              Id
+              Name {
+                value
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+`;
+
+const account = await sfGraphQL(GET_ACCOUNT, { id: '001...' });
+```
+
+GraphQL mutation example:
+
+```javascript
+const UPDATE_ACCOUNT = `
+  mutation UpdateAccount($id: ID!, $name: String!) {
+    uiapi {
+      AccountUpdate(input: {
+        Id: $id
+        Account: {
+          Name: { value: $name }
+        }
+      }) {
+        Record {
+          Id
+          Name {
+            value
+          }
+        }
+      }
+    }
+  }
+`;
+
+const result = await sfGraphQL(UPDATE_ACCOUNT, {
+  id: '001...',
+  name: 'New Name',
+});
+```
+
+## Einstein LLM Gateway (AI/Generative Features)
+
+Einstein LLM Gateway provides AI and generative capabilities for your React application. Use this service when you want to add features such as:
+
+- Text generation
+- Prompt-based AI responses
+- LLM-powered content creation
+- AI-assisted workflows
+
+### Einstein LLM Gateway Pattern
+
+```javascript
+async function callEinsteinGenerations({ prompt, model = 'gpt-4', signal }) {
+  const url = '/services/data/v62.0/einstein/llm/prompt/generations';
+  try {
+    const resp = await axios.post(
+      url,
+      {
+        additionalConfig: {
+          applicationName: 'PromptTemplateGenerationsInvocable',
+          model,
+        },
+        promptTextorId: prompt,
+      },
+      {
+        signal,
+      }
+    );
+    const data = resp.data;
+    return data?.generations?.[0]?.text || '';
+  } catch (error) {
+    throw new Error(
+      error.message || `Einstein LLM request failed (${error.status})`
+    );
+  }
+}
+```
+
+## Error Handling Pattern
+
+- Always implement robust try/catch for async operations.
+- Provide useful but safe error messages (no sensitive data leakage).
+
+```javascript
+async function safeFetch(recordId) {
+  try {
+    const data = await fetchRecord(recordId);
+    return data;
+  } catch (err) {
+    console.error('Salesforce UI API Error:', err);
+    throw err;
+  }
+}
+```
+
+## Anti-Patterns (Do NOT do these)
+
+- **Do NOT make UI/layout/theme/nav changes without updating appLayout.tsx** — If you add or change navigation, header, footer, sidebar, or overall layout, you must also edit the layout shell (`src/appLayout.tsx`). Leaving appLayout.tsx untouched while editing only pages or components is an error.
+- **Apex REST is not available in React applications** - Do NOT attempt to use or call Apex REST endpoints from React code
+- Unnecessary Apex controllers for simple UI API/GraphQL operations
+- Missing error handling for async operations
+- Hardcoded Salesforce URLs, IDs, or sensitive data
+- Ignoring field-level security and permission checks
+- Direct DOM manipulation in React components
+- Using LWC-specific patterns (`@wire`, LDS) or `@salesforce/*` modules in React
+
+## Security Standards (CRITICAL)
+
+- Validate user permissions before data operations.
+- Respect record sharing rules and field-level security.
+- Never hardcode credentials or secrets in client code.
+- Sanitize all user inputs.
+- Use HTTPS for all API calls.
+
+### Authentication Error Handling (MANDATORY)
+
+- All axios clients MUST include response interceptors that handle 401/403 errors.
+- When a 401 (Unauthorized) or 403 (Forbidden) response is received, trigger a page refresh with `window.location.reload()` to redirect to login.
+- Always return `Promise.reject(error)` after handling authentication errors to maintain proper error flow.
+
+### Notes
+
+- avoid swallowing errors.
+
+Input sanitization example:
+
+```javascript
+function sanitizeInput(input) {
+  if (typeof input !== 'string') return '';
+  return input
+    .trim()
+    .replace(/<script[^>]*>.*?<\/script>/gi, '')
+    .replace(/javascript:/gi, '')
+    .slice(0, 255);
+}
+```
+
+## Performance Standards
+
+- Implement client-side caching (e.g., RTK Query or React Query) for API data.
+- Use `React.memo`, `useMemo`, and `useCallback` where appropriate.
+- Implement proper loading and error states.
+
+## TypeScript Standards
+
+- Prefer TypeScript for React components and utilities.
+- Define clear and explicit interfaces for props and API data.
+
+## Testing Requirements
+
+- Use Jest + React Testing Library for UI tests.
+- Test loading, success, and error states for data-fetching components.
+
+## Application Generation Rules
+
+- When requested to generate a new application:
+  - Replace existing template content; do not append to the starter.
+  - Preserve the entry point and routes under `force-app/main/default/webapplications/<appName>/src/`.
+  - Keep existing build and deploy commands working.
+  - Follow the Data Access and Security standards above.
+
+## Debugging Guidance
+
+- Use React DevTools for component inspection.
+- Monitor the browser Network tab for REST/GraphQL calls and auth headers.
+- Implement Error Boundaries for unhandled exceptions.
+
+## Quality Checklist (for generated code)
+
+- Entry point maintained (`App.tsx` or `App.js` present and wired in routes/pages).
+- **Layout maintained (MANDATORY for UI work):** For any change that affects global layout, nav, header, footer, sidebar, or theme, you **must** have edited `appLayout.tsx`. If you did not open or modify appLayout.tsx, the change is incomplete — go back and update the layout file.
+- Uses shadcn/ui and Tailwind for UI.
+- Follows Data Access rules with proper auth and error handling.
+- Enforces Security standards and input sanitization.
+- Includes loading and error states.
+- Performance optimizations present where reasonable.
+- Tests cover core UI and data interactions.

package/dist/.a4drules/react_image_processing.md

@@ -0,0 +1,45 @@
+#Goal
+
+- You are configuring image usage for React applications generated through Vibe Coding. 
+- Your goal is to ensure Unsplash is used as the default image source unless the developer provides their own images.
+
+# AI Customization Rule: React Image Processing
+
+Image handling standards for React web apps (SFDX): CSP compliance, accessibility, and proper image sources.
+
+## Targets (File Pattern Matching)
+
+- `force-app/main/default/webapplications/*/**/*.tsx`
+- `force-app/main/default/webapplications/*/**/*.ts`
+- `force-app/main/default/webapplications/*/**/*.jsx`
+- `force-app/main/default/webapplications/*/**/*.js`
+- `force-app/main/default/webapplications/*/**/*.html`
+
+## Core Rules
+
+### Default Image Source: Unsplash
+
+Use Unsplash by default (pre-configured in CSP):
+
+```
+https://images.unsplash.com/photo-{PHOTO_ID}?w={WIDTH}&h={HEIGHT}&fit=crop&q=80
+```
+
+Sample Photo IDs: `1557683316-973673baf926` (tech), `1506905925346-21bda4d32df4` (nature)
+
+### Alternative Sources
+
+If user requests another source (Pexels, custom):
+
+- Use requested source
+- Inform user: "Add CSP Trusted Site in Setup → Security → CSP Trusted Sites"
+
+### Accessibility (MANDATORY)
+
+- Always include descriptive `alt` text
+- Use `alt=""` for decorative images only
+
+### Avoid (CSP Violations)
+
+- Avoid until requested `placeholder.com`, `picsum.photos`, `via.placeholder.com`  
+- Pre-configured: `images.unsplash.com`, `source.unsplash.com`, `images.pexels.com`

package/dist/.a4drules/typescript.md

@@ -0,0 +1,224 @@
+# AI Rule: TypeScript Standards
+
+Enforces strict TypeScript standards for type-safe React applications.
+
+## Targets
+- `**/*.ts`
+- `**/*.tsx`
+
+## MANDATORY Configuration
+- `strict: true` - Enable all strict type checking
+- `noUncheckedIndexedAccess: true` - Prevent unsafe array/object access
+- `noUnusedLocals: true` - Report unused variables
+- `noUnusedParameters: true` - Report unused parameters
+
+## Function Return Types (REQUIRED)
+```typescript
+// Always specify return types
+function fetchUserData(id: string): Promise<User> {
+  return api.get(`/users/${id}`);
+}
+
+const calculateTotal = (items: Item[]): number => {
+  return items.reduce((sum, item) => sum + item.price, 0);
+};
+```
+
+## Interface Definitions (REQUIRED)
+```typescript
+// Data structures
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  createdAt: Date;
+}
+
+// React component props
+interface ButtonProps {
+  variant: 'primary' | 'secondary';
+  onClick: () => void;
+  disabled?: boolean;
+  children: React.ReactNode;
+}
+
+export const Button: React.FC<ButtonProps> = ({ variant, onClick, disabled, children }) => {
+  // Implementation
+};
+```
+
+## Type Safety Rules
+
+### Never Use `any`
+```typescript
+// FORBIDDEN
+const data: any = await fetchData();
+
+// REQUIRED: Proper typing
+interface ApiResponse {
+  data: User[];
+  status: 'success' | 'error';
+}
+const response: ApiResponse = await fetchData();
+
+// ACCEPTABLE: Unknown when type is truly unknown
+const parseJson = (input: string): unknown => JSON.parse(input);
+```
+
+### Null Safety
+```typescript
+// Handle null/undefined explicitly
+interface UserProfile {
+  user: User | null;
+  loading: boolean;
+  error: string | null;
+}
+
+// Use optional chaining and nullish coalescing
+const displayName = user?.name ?? 'Anonymous';
+const avatarUrl = user?.profile?.avatar ?? '/default-avatar.png';
+```
+
+## React TypeScript Patterns
+
+### Event Handlers
+```typescript
+const handleSubmit = (event: React.FormEvent<HTMLFormElement>): void => {
+  event.preventDefault();
+};
+
+const handleInputChange = (event: React.ChangeEvent<HTMLInputElement>): void => {
+  setInputValue(event.target.value);
+};
+
+const handleClick = (event: React.MouseEvent<HTMLButtonElement>): void => {
+  console.log('Button clicked');
+};
+```
+
+### State and Hooks
+```typescript
+// Type useState properly
+const [user, setUser] = useState<User | null>(null);
+const [loading, setLoading] = useState<boolean>(false);
+const [errors, setErrors] = useState<string[]>([]);
+
+// Type custom hooks
+interface UseApiResult<T> {
+  data: T | null;
+  loading: boolean;
+  error: string | null;
+  refetch: () => Promise<void>;
+}
+
+function useApi<T>(url: string): UseApiResult<T> {
+  const [data, setData] = useState<T | null>(null);
+  const [loading, setLoading] = useState<boolean>(false);
+  const [error, setError] = useState<string | null>(null);
+
+  return { data, loading, error, refetch };
+}
+```
+
+## API Types
+
+### Salesforce Records
+```typescript
+interface SalesforceRecord {
+  Id: string;
+  attributes: { type: string; url: string };
+}
+
+interface Account extends SalesforceRecord {
+  Name: { value: string };
+  Industry?: { value: string | null };
+}
+
+// Type API functions
+async function fetchAccount(id: string): Promise<Account> {
+  const response = await axios.get<Account>(`/services/data/v62.0/ui-api/records/${id}`);
+  return response.data;
+}
+```
+
+### GraphQL
+```typescript
+interface GraphQLResponse<T> {
+  data: T;
+  errors?: Array<{ message: string; locations?: Array<{ line: number; column: number }> }>;
+}
+
+async function executeGraphQL<T>(query: string, variables?: Record<string, unknown>): Promise<T> {
+  const response = await axios.post<GraphQLResponse<T>>('/services/data/v62.0/graphql', {
+    query,
+    variables,
+  });
+
+  if (response.data.errors?.length) {
+    throw new Error(response.data.errors.map(e => e.message).join('; '));
+  }
+
+  return response.data.data;
+}
+```
+
+## Error Handling Types
+```typescript
+interface ApiError {
+  message: string;
+  status: number;
+  code?: string;
+}
+
+class CustomError extends Error {
+  constructor(message: string, public readonly status: number, public readonly code?: string) {
+    super(message);
+    this.name = 'CustomError';
+  }
+}
+```
+
+## Anti-Patterns (FORBIDDEN)
+
+### Type Assertions
+```typescript
+// FORBIDDEN: Unsafe assertions
+const user = data as User;
+
+// REQUIRED: Type guards
+function isUser(obj: unknown): obj is User {
+  return typeof obj === 'object' && obj !== null && typeof (obj as User).id === 'string';
+}
+
+if (isUser(data)) {
+  console.log(data.name); // Now safely typed
+}
+```
+
+### Missing Return Types
+```typescript
+// FORBIDDEN: No return type
+const fetchData = async (id: string) => {
+  return await api.get(`/data/${id}`);
+};
+
+// REQUIRED: Explicit return type
+const fetchData = async (id: string): Promise<ApiResponse> => {
+  return await api.get(`/data/${id}`);
+};
+```
+
+## Quality Checklist
+Before completing TypeScript code:
+1. All functions have explicit return types
+2. All interfaces are properly defined
+3. No `any` types used (use `unknown` if necessary)
+4. Null/undefined handling is explicit
+5. React components are properly typed
+6. API calls have proper type definitions
+7. `tsc -b` compiles without errors
+
+## Enforcement
+- TypeScript errors MUST be fixed before any commit
+- NEVER disable TypeScript strict mode
+- Code reviews MUST check for proper typing

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

@@ -0,0 +1,23 @@
+# UI layout: always update appLayout.tsx (MANDATORY)
+
+**Build navigation into the app layout:** The app layout (e.g. `appLayout.tsx`) must **include** the navigation—header nav, sidebar, or both—so that every routed page is wrapped by the same shell and nav. Do not omit nav from the layout or rely on per-page nav only.
+
+## Targets (File Pattern Matching)
+
+Apply this rule when editing React UI or layout:
+
+- `force-app/main/default/webapplications/*/src/appLayout.tsx`
+- `force-app/main/default/webapplications/*/src/**/*.tsx`
+- `force-app/main/default/webapplications/*/src/**/*.jsx`
+
+## Rule (CRITICAL)
+
+**When making any UI change** that affects navigation, header, footer, sidebar, theme, or overall layout:
+
+1. **You MUST also edit `src/appLayout.tsx`** (the theme layout used by `routes.tsx`).
+2. Do not only edit pages or components and leave `appLayout.tsx` unchanged.
+3. Before finishing: confirm you opened and modified `appLayout.tsx` if the change touches layout/nav/theme. If you did not, the task is incomplete — update the layout file.
+
+**Navigation menu and placeholder name/design (often missed):** When editing the layout, **always** update (1) the **navigation menu**—replace default nav items and labels with app-specific links and names; do not leave template "Home"/"About" or placeholder links; (2) the **app name** in header/nav brand/footer and in `index.html` `<title>`—use the actual app name, not the template placeholder; (3) any **placeholder design** in the shell so it matches the app. See **webapp-nav-and-placeholders.md**.
+
+Path: `force-app/main/default/webapplications/<appName>/src/appLayout.tsx` (or the app's layout file that `routes.tsx` imports). (or the app’s layout file that `routes.tsx` imports).