@salesforce/ui-bundle-template-feature-react-global-search 1.117.2

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,250 @@
+# Feature: React Global Search (Single Object)
+
+This package is a **reference implementation** for adding global search (keyword search, filters, results list, and record detail) to a Salesforce UI Bundle. It provides **API services, hooks, types/schemas, and utilities** so you can **build your own UI** and import the data layer from the package—or optionally **copy** the reference UI from the package and adapt it.
+
+**Intended use (vibing model):**
+
+- **Do not copy the feature source** (api, hooks, types, utils).
+- **Build your own UI** (recommended), or **copy** the reference pages/components from the package and adapt.
+- **Import** data-layer pieces from the package: services, hooks, types, utilities.
+
+UI components and feature constants are deliberately **not exported** from the public API.
+
+---
+
+## What you get (public API)
+
+Import from the package root:
+
+```ts
+import {
+  objectInfoService,
+  objectDetailService,
+  useObjectListMetadata,
+  useRecordListGraphQL,
+  useRecordDetailLayout,
+  useObjectColumns,
+  useObjectFilters,
+  useObjectInfoBatch,
+  type FilterCriteria,
+  parseFilterValue,
+  sanitizeFilterValue,
+} from "@salesforce/ui-bundle-template-feature-react-global-search";
+```
+
+### API services
+
+- **`objectInfoService`**
+  - `getObjectInfoBatch(objectApiNames)` (GraphQL uiapi.objectInfos)
+  - `getPicklistValues(objectApiName, fieldName, recordTypeId?)` (GraphQL uiapi.objectInfos)
+  - `getObjectListFilters(objectApiName)` (REST search-info filters)
+- **`objectDetailService`**
+  - `getLayout(objectApiName, recordTypeId?)` (REST layout)
+  - `getRecordDetail(objectApiName, recordId, recordTypeId?)` (layout + object info + record)
+- **GraphQL record helpers**
+  - `getRecordsGraphQL(...)` (list query, `first + after`)
+  - `getRecordByIdGraphQL(...)` (single record by Id)
+  - `buildWhereFromCriteria(...)`, `buildOrderByFromSort(...)`, `buildGetRecordsQuery(...)`
+
+### Hooks
+
+- **List metadata**: `useObjectListMetadata(objectApiName)` — filters, columns (derived from filters), picklistValues.
+- **List columns (legacy)**: `useObjectColumns(objectApiName)` — columns, columnsLoading, columnsError.
+- **List filters**: `useObjectFilters(objectApiName)` — filtersData (filters + picklist values per object).
+- **List records**: `useRecordListGraphQL({ objectApiName, first, after, filters, sortBy, searchQuery, columns? })` — GraphQL list with cursor pagination.
+- **Detail**: `useRecordDetailLayout({ objectApiName, recordId, recordTypeId?, initialData? })` — layout (REST) + object metadata + record (GraphQL).
+- **Batch object info**: `useObjectInfoBatch(objectApiNames)` — objectInfos, loading, error.
+
+### Types, schemas, utils
+
+- **Types**: `Filter`, `FilterCriteria`, `Column`, `SearchResultRecord`, `LayoutResponse`, `ObjectInfoResult`, …
+- **Zod schemas**: `LayoutResponseSchema`, `ObjectInfoResultSchema`, `SearchResultsResponseSchema`, …
+- **Utilities**: `parseFilterValue`, `sanitizeFilterValue`, `createFiltersKey`, `getGraphQLNodeValue`, `graphQLNodeToSearchResultRecordData`, `fetchAndValidate`, `safeEncodePath`, `getNestedFieldValue`, `getRecordDisplayName`, layout transform and form helpers, etc.
+
+The definitive type surface is in `index.d.ts` in this package.
+
+---
+
+## Features
+
+- **Single object browse & search**: keyword search and “browse all” mode (`browse__all`).
+- **Filterable list**: filter definitions + picklist values, criteria → GraphQL where clause.
+- **Sortable list**: build orderBy from sort selection.
+- **Cursor pagination (forward-only)** with **previous-page simulation via cursor stack**.
+- **Record detail**: layout-driven field selection (layout REST + record GraphQL).
+- **Type safety**: Zod validation + exported TypeScript types.
+
+---
+
+## Architecture
+
+### Data layer (GraphQL vs REST)
+
+- **GraphQL (uiapi)**  
+  Object metadata via `getObjectInfoBatch` and `getPicklistValues`. Records via `getRecordsGraphQL` and `getRecordByIdGraphQL`.
+- **REST (uiApiClient)**  
+  Layout from `GET /layout/{object}`. Search filters from `GET /search-info/{object}/filters`. List/search results are **GraphQL-only** via `useRecordListGraphQL` (no REST keyword search in the public API).
+
+In the reference implementation:
+
+- **Detail page**: `useRecordDetailLayout` → `objectDetailService.getRecordDetail` (layout REST + record GraphQL).
+- **List page**: `useObjectListMetadata` (filters + columns + picklists) + `useRecordListGraphQL` (records).
+
+### API flow (conceptual)
+
+- **Initialization**: `getObjectInfoBatch` for object metadata; per object: `getObjectListFilters` (columns derived from filters), then `getPicklistValues` for picklist filters.
+- **List/search**: `useRecordListGraphQL` (GraphQL UI API with cursor pagination; use a cursor stack for “Previous”).
+- **Detail**: `useRecordDetailLayout` / `objectDetailService.getRecordDetail`.
+
+All API calls use `fetchAndValidate` and validate with Zod.
+
+---
+
+## Install
+
+```bash
+npm install @salesforce/ui-bundle-template-feature-react-global-search
+```
+
+### Required peer environment
+
+- `@salesforce/ui-bundle` (API proxy, auth, etc.)
+- React and React Router
+
+If you are not using that stack, you can still reuse **pure** utilities and types; the API services and hooks need an equivalent UI API transport.
+
+---
+
+## Configuration (constants)
+
+Constants are **not exported**. When you build your app (or copy reference UI), define them in the app:
+
+- **OBJECT_API_NAMES** – Array of object API names to search. First element is the primary object (e.g. `OBJECT_API_NAMES[0]`). Default to `["Account"]` if no object is specified.
+- **DEFAULT_PAGE_SIZE** – e.g. `20`.
+- **DEFAULT_DETAIL_PAGE_TITLE** – e.g. `"Untitled"`.
+
+**Determining the search object:** Decide from the user’s request or app context. If the user does not specify an object, use **Account**. If your repo provides a script (e.g. `scripts/parse-feature-install-context.cjs`), you can use it to parse the user prompt and get an object API name or label hint; otherwise set OBJECT_API_NAMES in the app’s constants accordingly.
+
+---
+
+## Vibing integration (recommended: build your own UI)
+
+1. **Routes**  
+   Search results: e.g. `/global-search/:query` (use `browse__all` for “show all”). Record detail: e.g. `/object/:objectApiName/:recordId`.
+
+2. **Search entry**  
+   On submit, navigate to `/global-search/${encodeURIComponent(query)}` or `/global-search/browse__all`.
+
+3. **Results page (list)**  
+   Use `useObjectListMetadata(objectApiName)` for filters/columns/picklists and `useRecordListGraphQL({ objectApiName, first, after, filters, sortBy, searchQuery, columns })` for records. Implement a **cursor stack** for “Previous” (see reference `GlobalSearch` page).
+
+4. **Detail page**  
+   Use `useRecordDetailLayout({ objectApiName, recordId })` for `layout`, `record`, `objectMetadata`; render with `layoutTransformUtils` and `graphQLNodeFieldUtils` (or equivalent).
+
+5. **Search input placement**  
+   Put the search entry on the **Home page** (e.g. as a card) or in the app **Header**—**not** in a root layout that wraps every page.
+
+---
+
+## Optional: copy reference UI from the package
+
+The package **does not export** UI components. If you prefer to copy the reference UI instead of building your own:
+
+- **What to import (do not copy):** API (`objectInfoService`, `objectDetailService`, …), hooks (`useObjectListMetadata`, `useRecordListGraphQL`, `useRecordDetailLayout`, …), types, Zod schemas, utilities.
+- **What to copy into the app:** A single **constants** file (set `OBJECT_API_NAMES` to your chosen object(s)) and the **pages** and **components** from the package’s reference implementation.
+
+**Path convention (reference implementation in this repo):**
+
+All paths below are relative to the **package root** of this feature. The reference implementation lives under:
+
+`src/force-app/main/default/uiBundles/feature-react-global-search/src/features/global-search/`
+
+Example paths:
+
+- Constants: `src/force-app/main/default/uiBundles/feature-react-global-search/src/features/global-search/constants.ts`
+- Search page: `src/force-app/main/default/uiBundles/feature-react-global-search/src/features/global-search/pages/GlobalSearch.tsx`
+- Components: `src/force-app/main/default/uiBundles/feature-react-global-search/src/features/global-search/components/`
+
+After copying **pages/** and **components/** into your app:
+
+1. In the **copied files only**, replace imports from `@/api`, `@/hooks`, `@/types`, `@/utils`, `@/lib`, `@/features` with imports from **`@salesforce/ui-bundle-template-feature-react-global-search`**.
+2. Keep constants and component-to-component imports pointing at your app’s copied constants and components.
+3. Adapt markup and styles to your app’s UI library (the reference uses shadcn and Tailwind).
+
+---
+
+## Example: build filters → FilterCriteria[]
+
+```ts
+import {
+  parseFilterValue,
+  sanitizeFilterValue,
+  type FilterCriteria,
+} from "@salesforce/ui-bundle-template-feature-react-global-search";
+
+function toCriteria(
+  objectApiName: string,
+  fieldPath: string,
+  operator: "eq" | "like",
+  rawValues: string[],
+): FilterCriteria {
+  return {
+    objectApiName,
+    fieldPath,
+    operator,
+    values: rawValues
+      .map((v) => sanitizeFilterValue(v))
+      .filter(Boolean)
+      .map((v) => parseFilterValue(v)),
+  };
+}
+```
+
+---
+
+## Implementation steps (for an agent)
+
+1. **Install**  
+   From the consumer app root: `npm install @salesforce/ui-bundle-template-feature-react-global-search`.
+
+2. **Determine search object(s)**  
+   From user prompt or app context. Default to **Account** if none specified. Set `OBJECT_API_NAMES` in the app’s constants to this value.
+
+3. **Constants**  
+   In the app, create a constants file (or copy from the package reference path above) and set `OBJECT_API_NAMES`, `DEFAULT_PAGE_SIZE`, `DEFAULT_DETAIL_PAGE_TITLE`.
+
+4. **API / types / utils / hooks**  
+   **Import** only from the package. Do **not** create or copy `api/`, `hooks/`, `types/`, or `utils/` in the app.
+
+5. **UI**  
+   Either **(a)** build your own UI using the package’s hooks and types, or **(b)** copy the full **pages/** and **components/** from the package reference path into the app, then batch-replace imports in the copied files to use the package (see “Optional: copy reference UI” above).
+
+6. **Routes and search input**  
+   Add routes for search (e.g. `/global-search/:query`) and record detail (e.g. `/object/:objectApiName/:recordId`). Place the search input on the **Home page** or in the **Header** only—not in a root layout.
+
+### Checklist
+
+- [ ] Package installed.
+- [ ] Search object(s) determined; `OBJECT_API_NAMES` set in app constants.
+- [ ] API, types, utils, hooks **imported** from package only (no api/hooks/types/utils folders in app).
+- [ ] UI: own implementation **or** full copy of reference pages/components with imports updated to the package.
+- [ ] Routes and search entry placement done; GlobalSearchInput not in root layout.
+
+---
+
+## Notes / constraints
+
+- **Single-object scope**: The package’s APIs and hooks are designed for one CRM object at a time (one `objectApiName` per call). There is no built-in multi-object search or tabbed results. You can still implement **multi-object CRM search** by calling the same services and hooks once per object (e.g. in parallel or per tab), then combining the results and building your own UI (tabs, merged lists, or separate sections).
+- **Layout is REST**: record layout from UI API REST; record and object metadata are GraphQL-backed.
+- **No UI exports**: build or copy UI in the app; import only the data layer from the package.
+
+---
+
+## Local development (this repo)
+
+When developing this feature inside the ui-bundle repo:
+
+```bash
+nx run @salesforce/ui-bundle-template-feature-react-global-search:build:dist-app
+nx run @salesforce/ui-bundle-template-feature-react-global-search:dev
+```

package/dist/.forceignore

@@ -0,0 +1,15 @@
+# List files or directories below to ignore them when running force:source:push, force:source:pull, and force:source:status
+# More information: https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_exclude_source.htm
+#
+
+package.xml
+
+# LWC configuration files
+**/jsconfig.json
+**/.eslintrc.json
+
+# LWC Jest
+**/__tests__/**
+
+node_modules/
+.DS_Store

package/dist/.husky/pre-commit

@@ -0,0 +1,4 @@
+#!/bin/sh
+. "$(dirname "$0")/_/husky.sh"
+
+npm run precommit

package/dist/.prettierignore

@@ -0,0 +1,11 @@
+# List files or directories below to ignore them when running prettier
+# More information: https://prettier.io/docs/en/ignore.html
+#
+
+**/staticresources/**
+.localdevserver
+.sfdx
+.sf
+.vscode
+
+coverage/

package/dist/.prettierrc

@@ -0,0 +1,17 @@
+{
+  "trailingComma": "none",
+  "plugins": [
+    "prettier-plugin-apex",
+    "@prettier/plugin-xml"
+  ],
+  "overrides": [
+    {
+      "files": "**/lwc/**/*.html",
+      "options": { "parser": "lwc" }
+    },
+    {
+      "files": "*.{cmp,page,component}",
+      "options": { "parser": "html" }
+    }
+  ]
+}

package/dist/AGENT.md

@@ -0,0 +1,193 @@
+# Agent guide: Salesforce UI Bundle development
+
+This project is a **Salesforce DX (SFDX) project** containing a **React UI Bundle**. The UI Bundle is a standalone Vite + React SPA that runs inside the Salesforce platform. Use this file when working in this project.
+
+## Resolving paths
+
+Read `sfdx-project.json` at the project root. Take the first `packageDirectories[].path` value and append `/main/default` to get `<sfdx-source>`. The UI Bundle directory is:
+
+```
+<sfdx-source>/uiBundles/<appName>/
+```
+
+Replace `<appName>` with the actual folder name found under `uiBundles/`. The source path is **not** always `force-app` — always resolve it from `sfdx-project.json`.
+
+## Project layout
+
+```
+<project-root>/
+├── sfdx-project.json
+├── package.json                         # SFDX root scripts 
+├── scripts/
+│   ├── setup-cli.mjs                    # One-command setup (deploy, schema, build)
+│   └── graphql-search.sh               # Schema entity lookup
+├── config/
+│   └── project-scratch-def.json
+│
+└── <sfdx-source>/
+    ├── uiBundles/
+    │   └── <appName>/                   # ← React UI Bundle (primary workspace)
+    │       ├── <appName>.uibundle-meta.xml
+    │       ├── ui-bundle.json
+    │       ├── index.html
+    │       ├── package.json
+    │       ├── vite.config.ts / tsconfig.json
+    │       ├── vitest.config.ts / playwright.config.ts
+    │       ├── codegen.yml / .graphqlrc.yml
+    │       └── src/                     # All application code lives here
+    │
+    ├── classes/                          # Apex classes (optional)
+    ├── objects/                          # Custom objects and fields (optional)
+    ├── permissionsets/                   # Permission sets (optional)
+    ├── cspTrustedSites/                 # CSP trusted site definitions (optional)
+    ├── layouts/                          # Object layouts (optional)
+    ├── triggers/                         # Apex triggers (optional)
+    └── data/                            # Sample data for import (optional)
+```
+
+## Web application source structure
+
+All application code lives inside the UI Bundle's `src/` directory:
+
+```
+src/
+├── app.tsx                  # Entry point — creates the browser router
+├── appLayout.tsx            # Shell layout (header, navigation, Outlet, footer)
+├── routes.tsx               # Single route registry for the entire app
+├── navigationMenu.tsx       # Navigation component
+├── router-utils.tsx         # Router helpers
+├── lib/utils.ts             # Utility functions (cn, etc.)
+├── styles/global.css        # Tailwind global styles
+├── api/                     # GraphQL operations, clients, data services
+├── assets/                  # Static SVGs, images
+├── components/
+│   ├── ui/                  # Shared primitives (shadcn-style: button, card, input, etc.)
+│   ├── layout/              # Layout components (header, footer, sidebar)
+│   └── <feature>/           # Feature-specific components
+├── features/                # Feature modules (auth, search, etc.)
+├── hooks/                   # Custom React hooks
+├── pages/                   # Page components (one per route)
+├── public/                  # Static assets served as-is
+└── utils/                   # Shared utilities
+```
+
+### Key files
+
+| File | Role |
+|------|------|
+| `app.tsx` | Creates `BrowserRouter`; do not add UI here |
+| `appLayout.tsx` | Source of truth for navigation, header, footer, and page shell |
+| `routes.tsx` | Single route registry; all pages are children of the layout route |
+| `<appName>.uibundle-meta.xml` | Salesforce deploy descriptor (`masterLabel`, `version`, `isActive`) |
+| `ui-bundle.json` | Runtime config (`outputDir`, routing) |
+
+## Two package.json contexts
+
+### 1. Project root
+
+Used for SFDX metadata tooling. Scripts here target LWC/Aura, not the React app.
+
+| Command | Purpose |
+|---------|---------|
+| `npm run test` | LWC Jest (passWithNoTests) |
+| `npm run prettier` | Format metadata files |
+| `npm run prettier:verify` | Check Prettier |
+
+**One-command setup:** `node scripts/setup-cli.mjs --target-org <alias>` runs login, deploy, permset assignment, data import, GraphQL schema/codegen, UI Bundle build, and optionally the dev server. Use `--help` for all flags.
+
+### 2. Web app directory (primary workspace)
+
+**Always `cd` into the UI Bundle directory for dev/build/lint/test:**
+
+| Command | Purpose |
+|---------|---------|
+| `npm run dev` | Start Vite dev server |
+| `npm run build` | TypeScript check + Vite production build |
+| `npm run lint` | ESLint for the React app |
+| `npm run test` | Vitest unit tests |
+| `npm run preview` | Preview production build |
+| `npm run graphql:codegen` | Generate GraphQL types from schema |
+| `npm run graphql:schema` | Fetch GraphQL schema from org |
+
+**Before completing any change:** run `npm run build` and `npm run lint` from the UI Bundle directory. Both must pass with zero errors.
+
+## Development conventions
+
+### UI
+
+- **Component library:** shadcn/ui primitives in `src/components/ui/`. Always use these over raw HTML equivalents.
+- **Styling:** Tailwind CSS only. No inline `style={{}}`. Use `cn()` from `@/lib/utils` for conditional classes.
+- **Icons:** Lucide React.
+- **Path alias:** `@/*` maps to `src/*`. Use it for all imports.
+- **TypeScript:** No `any`. Use proper types, generics, or `unknown`.
+- **Components:** Accept `className?: string` prop. Extract shared state to custom hooks in `src/hooks/`.
+- **React apps must not** import Salesforce platform modules (`lightning/*`, `@wire`, LWC APIs).
+
+### Routing
+
+- React Router with `createBrowserRouter`. Route definitions live exclusively in `routes.tsx`.
+- All page routes are children of the layout route (which renders `appLayout.tsx`).
+- Default-export one component per page file.
+- The catch-all `path: '*'` route must always be last.
+- Navigation uses absolute paths (`/dashboard`). Non-router imports use dot-relative paths (`./utils`).
+- Navigation visibility is driven by `handle.showInNavigation` on route definitions.
+
+### Layout and navigation
+
+- `appLayout.tsx` owns the header, navigation menu, footer, and `<Outlet />`.
+- To modify header or footer, edit `appLayout.tsx` and create components in `src/components/layout/`.
+- To add a page, add a route in `routes.tsx` and create the page component — do not modify `appLayout.tsx` or `app.tsx` for page additions.
+
+### Data access (Salesforce)
+
+- **All data access uses the Data SDK** (`@salesforce/sdk-data`) via `createDataSDK()`.
+- **Never** use `fetch()` or `axios` directly for Salesforce data.
+- **GraphQL is preferred** for record operations (`sdk.graphql`). Use `sdk.fetch` only when GraphQL cannot cover the case (UI API REST, Apex REST, Connect REST, Einstein LLM).
+- Use optional chaining: `sdk.graphql?.()`, `sdk.fetch?.()`.
+- Apply the `@optional` directive to all record fields for field-level security resilience.
+- Verify field and object names via `scripts/graphql-search.sh` before writing queries.
+- Use `__SF_API_VERSION__` global for API version in REST calls.
+- **Blocked APIs:** Enterprise REST query endpoint (`/query` with SOQL), `@AuraEnabled` Apex, Chatter API.
+
+### CSP trusted sites
+
+Any external domain the app calls (APIs, CDNs, fonts) must have a `.cspTrustedSite-meta.xml` file under `<sfdx-source>/cspTrustedSites/`. Unregistered domains are blocked at runtime. Each subdomain needs its own entry. URLs must be HTTPS with no trailing slash, no path, and no wildcards.
+
+## Deploying
+
+**Deployment order matters.** Metadata (objects, permission sets) must be deployed before fetching the GraphQL schema. After any metadata deployment that changes objects, fields, or permissions, re-run schema fetch and codegen.
+
+**Recommended sequence:**
+
+1. Authenticate to the target org
+2. Build the UI Bundle (`npm run build` in the UI Bundle directory)
+3. Deploy metadata (`sf project deploy start --source-dir <packageDir> --target-org <alias>`)
+4. Assign permission sets
+5. Import data (only with user confirmation)
+6. Fetch GraphQL schema + run codegen (`npm run graphql:schema && npm run graphql:codegen`)
+7. Rebuild the UI Bundle (schema changes may affect generated types)
+
+**Or use the one-command setup:** `node scripts/setup-cli.mjs --target-org <alias>`
+
+```bash
+# Deploy UI Bundle only
+sf project deploy start --source-dir <sfdx-source>/ui-bundles --target-org <alias>
+
+# Deploy all metadata
+sf project deploy start --source-dir <packageDir> --target-org <alias>
+```
+
+## Skills
+
+Check for available skills before implementing any of the following:
+
+| Area | When to consult |
+|------|----------------|
+| UI generation | Building pages, components, modifying header/footer/layout |
+| Salesforce data access | Reading/writing records, GraphQL queries, REST calls |
+| Metadata and deployment | Scaffolding apps, configuring CSP, deployment sequencing |
+| Feature installation | Before building something from scratch — check if a pre-built feature exists |
+| File upload | Adding file upload with Salesforce ContentVersion |
+| Agentforce conversation | Adding or modifying the Agentforce chat widget |
+
+Skills are the authoritative source for detailed patterns, constraints, and code examples in each area. This file provides project-level orientation; skills provide implementation depth.