@salesforce/ui-bundle-template-app-react-template-b2e 1.119.0 → 1.119.2

package/dist/AGENT.md

@@ -45,7 +45,7 @@ Replace `<appName>` with the actual folder name found under `uiBundles/`. The so
     └── data/                            # Sample data for import (optional)
 ```
 
-## Web application source structure
+## UI Bundle source structure
 
 All application code lives inside the UI Bundle's `src/` directory:
 
@@ -95,9 +95,11 @@ Used for SFDX metadata tooling. Scripts here target LWC/Aura, not the React app.
 
 **One-time org setup:** `node scripts/org-setup.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)
+### 2. UI Bundle directory (primary workspace)
 
-**Always `cd` into the UI Bundle directory for dev/build/lint/test:**
+**ALL dev, build, lint, and test commands MUST be run from inside the UI Bundle directory (`<sfdx-source>/uiBundles/<appName>/`). Never run them from the project root.**
+
+Resolve the correct path from `sfdx-project.json` before running any command. Do not hardcode the path.
 
 | Command | Purpose |
 |---------|---------|
@@ -109,13 +111,17 @@ Used for SFDX metadata tooling. Scripts here target LWC/Aura, not the React app.
 | `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.
+**After every task, without exception:**
+1. Run `npm run build` from the UI Bundle directory — must pass with zero errors.
+2. Run `npm run lint` from the UI Bundle directory — must pass with zero errors.
+3. Run `npm run dev` to start the dev server so the user can verify the result.
 
+Do not consider a task complete until all three steps have been run successfully.
 ## Development conventions
 
 ### UI
 
-- **Component library:** shadcn/ui primitives in `src/components/ui/`. Always use these over raw HTML equivalents.
+- **Component library:** shadcn/ui primitives in `src/components/ui/`. Always use these over raw HTML equivalents. **Before importing any component, verify both the file exists in `src/components/ui/` AND the named export exists within that file.** Never assume a component or export is available — read the file to confirm the exact exports before importing.
 - **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.
@@ -140,6 +146,10 @@ Used for SFDX metadata tooling. Scripts here target LWC/Aura, not the React app.
 
 ### Data access (Salesforce)
 
+**Before writing any code that connects to Salesforce, you MUST invoke the `using-ui-bundle-salesforce-data` skill. Do not write any data access code without consulting it first.**
+
+This applies to: GraphQL queries/mutations, REST calls, SDK initialization, custom hooks that fetch data, or any code that imports from `@salesforce/sdk-data`.
+
 - **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).
@@ -149,25 +159,74 @@ Used for SFDX metadata tooling. Scripts here target LWC/Aura, not the React app.
 - Use `__SF_API_VERSION__` global for API version in REST calls.
 - **Blocked APIs:** Enterprise REST query endpoint (`/query` with SOQL), `@AuraEnabled` Apex, Chatter API.
 
+#### Permitted APIs
+
+| API | Method | Endpoints / Use Case |
+|-----|--------|----------------------|
+| GraphQL | `sdk.graphql` | All record queries and mutations via `uiapi { }` namespace |
+| UI API REST | `sdk.fetch` | `/services/data/v{ver}/ui-api/records/{id}` |
+| Apex REST | `sdk.fetch` | `/services/apexrest/{resource}` |
+| Connect REST | `sdk.fetch` | `/services/data/v{ver}/connect/...` |
+| Einstein LLM | `sdk.fetch` | `/services/data/v{ver}/einstein/llm/prompt/generations` |
+
+Any endpoint not listed above is not permitted.
+
+#### GraphQL non-negotiable rules
+
+1. **Schema is the single source of truth** — every entity and field name must be confirmed via the schema search script before use. Never guess.
+2. **`@optional` on all record fields** — FLS causes entire queries to fail if any field is inaccessible. Apply to every scalar, parent, and child relationship field.
+3. **Correct mutation syntax** — mutations wrap under `uiapi(input: { allOrNone: true/false })`, not bare `uiapi { ... }`.
+4. **Explicit `first:` in every query** — omitting it silently defaults to 10 records. Always include `pageInfo { hasNextPage endCursor }` for paginated queries.
+5. **SOQL-derived execution limits** — max 10 subqueries per request, max 5 levels of child-to-parent traversal, max 1 level parent-to-child, max 2,000 records per subquery.
+6. **HTTP 200 does not mean success** — Salesforce returns HTTP 200 even on failure. Always check the `errors` array in the response body.
+
+#### GraphQL inline queries
+Must use the `gql` template tag from `@salesforce/sdk-data` — plain template strings bypass `@graphql-eslint` schema validation. For complex queries, use external `.graphql` files with codegen.
+
+#### Current user info
+Use GraphQL (`uiapi { currentUser { Id Name { value } } }`), not Chatter (`/chatter/users/me`).
+
+#### Schema file (`schema.graphql`)
+
+The `schema.graphql` file at the SFDX project root is the source of truth for all entity and field name lookups. It is 265K+ lines — never open or parse it directly. Use the schema search script instead.
+
+- **Generate/refresh:** Run `npm run graphql:schema` from the UI bundle directory
+- **When to regenerate:** After any metadata deployment that changes objects, fields, or permission sets
+- **Custom objects** only appear in the schema after metadata deployment AND permission set assignment
+- **After regenerating:** Always re-run `npm run graphql:codegen` and `npm run build` (schema changes may affect generated types)
+
 ### 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.
 
+## Building and launching the app
+
+All build, dev, and test commands run from the UI Bundle directory. Before running any command, read the UI Bundle's `package.json` to confirm available scripts — do not assume script names.
+
+Typical scripts found in the UI Bundle:
+
+| Command | Purpose |
+|---------|---------|
+| `npm run build` | TypeScript check + Vite production build |
+| `npm run dev` | Start Vite dev server |
+| `npm run lint` | ESLint |
+| `npm run test` | Vitest unit tests |
+| `npm run graphql:codegen` | Generate GraphQL types |
+| `npm run graphql:schema` | Fetch GraphQL schema from org |
+
+If dependencies have not been installed yet, run `npm install` in the UI Bundle directory first. Alternatively, run `npm run sf-project-setup` from the project root — it resolves the UI Bundle directory automatically and runs install, build, and dev in sequence.
+
+**After any JavaScript or TypeScript change, run `npm run build` to validate the change.** If the build fails, read the error output, identify the cause, fix it, and run `npm run build` again. Do not move on until the build passes.
+
 ## 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:**
+**Deployment steps:**
 
 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-time org setup:** `node scripts/org-setup.mjs --target-org <alias>`
 
 ```bash
 # Deploy UI Bundle only
@@ -177,17 +236,17 @@ sf project deploy start --source-dir <sfdx-source>/ui-bundles --target-org <alia
 sf project deploy start --source-dir <packageDir> --target-org <alias>
 ```
 
-## Skills
+**Do not open the app after deployment.** Do not run `sf org open`, do not guess the runtime URL, and do not construct paths like `/s/<appName>`. Deployment is complete when the `sf project deploy start` command succeeds.
 
-Check for available skills before implementing any of the following:
+## Post-deployment org setup
 
-| 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 |
+These steps apply after a fresh deployment to configure the org. They are not part of routine deployment.
+
+1. Assign permission sets
+2. Import data (only with user confirmation)
+3. Fetch GraphQL schema + run codegen (`npm run graphql:schema && npm run graphql:codegen`)
+4. Rebuild the UI Bundle (`npm run build` — schema changes may affect generated types)
+
+## Skills
 
-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.
+Before starting any task, check whether a relevant skill exists. If one does, invoke it before writing any code or making any implementation decision. Skills are the authoritative source for patterns, constraints, and code examples.

package/dist/CHANGELOG.md

@@ -3,6 +3,22 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [1.119.2](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.119.1...v1.119.2) (2026-03-31)
+
+**Note:** Version bump only for package @salesforce/ui-bundle-template-base-sfdx-project
+
+
+
+
+
+## [1.119.1](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.119.0...v1.119.1) (2026-03-31)
+
+**Note:** Version bump only for package @salesforce/ui-bundle-template-base-sfdx-project
+
+
+
+
+
 # [1.119.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.118.4...v1.119.0) (2026-03-31)
 
 **Note:** Version bump only for package @salesforce/ui-bundle-template-base-sfdx-project

package/dist/README.md

@@ -8,19 +8,42 @@ This project ships the UI Bundle only. No additional Salesforce metadata (object
 
 | Path                                                 | Description                             |
 | ---------------------------------------------------- | --------------------------------------- |
-| `force-app/main/default/uiBundles/reactinternalapp/` | React UI Bundle (source, config, tests) |
+| `force-app/main/default/uibundles/reactinternalapp/` | React UI Bundle (source, config, tests) |
 
 ## Getting started
 
-Navigate to the UI Bundle and install dependencies:
+Install project dependencies and start the local dev server:
 
 ```bash
-cd force-app/main/default/uiBundles/reactinternalapp
 npm install
-npm run dev
+npm run sf-project-setup
 ```
 
-Opens at http://localhost:5173 by default. For build and test instructions, see the [UI Bundle README](force-app/main/default/uiBundles/reactinternalapp/README.md).
+This installs the UI Bundle dependencies, builds the app, and opens the dev server at http://localhost:5173. For manual build and test instructions, see the [UI Bundle README](force-app/main/default/uiBundles/reactinternalapp/README.md).
+
+## Add features
+
+Use the features CLI to install additional UI features into the UI Bundle.
+
+List all available features:
+
+```bash
+npx @salesforce/ui-bundle-features-experimental list
+```
+
+Get details about a specific feature (description, dependencies, files, and integration examples):
+
+```bash
+npx @salesforce/ui-bundle-features-experimental describe <feature-name>
+```
+
+Install a feature:
+
+```bash
+npx @salesforce/ui-bundle-features-experimental install <feature-name> --ui-bundle-dir reactinternalapp
+```
+
+After installation, the CLI will list any `__example__` files that need manual integration. Read each example file to see the integration pattern, apply it to the target file, then delete the example file.
 
 ## Deploy
 
@@ -35,11 +58,43 @@ sf project deploy start --source-dir force-app --target-org <alias>
 
 ```bash
 cd force-app/main/default/uiBundles/reactinternalapp && npm install && npm run build && cd -
-sf project deploy start --source-dir force-app/main/default/ui-bundles --target-org <alias>
+sf project deploy start --source-dir force-app/main/default/uiBundles --target-org <alias>
 ```
 
 Replace `<alias>` with your target org alias.
 
+## Setup scripts
+
+Two npm scripts at the project root streamline getting started and deployment.
+
+**`npm run sf-project-setup`** — installs the UI Bundle dependencies, builds the app, and starts the dev server (see [Getting started](#getting-started)).
+
+**`npm run setup`** — runs the full deployment setup in one command: org login (if needed), UI Bundle build, deploy the UI Bundle, fetch GraphQL schema, run codegen, and optionally start the dev server:
+
+```bash
+npm run setup -- --target-org <alias>
+```
+
+Running without flags presents an interactive step picker. Pass `--yes` to skip it and run all steps immediately:
+
+```bash
+npm run setup -- --target-org <alias> --yes
+```
+
+Common options:
+
+| Option                    | Description                                    |
+| ------------------------- | ---------------------------------------------- |
+| `--skip-login`            | Skip browser login (org already authenticated) |
+| `--skip-deploy`           | Do not deploy metadata                         |
+| `--skip-graphql`          | Skip GraphQL schema fetch and codegen          |
+| `--skip-ui-bundle-build`  | Skip `npm install` and UI Bundle build         |
+| `--skip-dev`              | Do not start the dev server at the end         |
+| `--ui-bundle-name <name>` | UI Bundle folder name when multiple exist      |
+| `-y, --yes`               | Skip interactive step picker; run all steps    |
+
+For all options: `npm run setup -- --help`.
+
 ## Configure Your Salesforce DX Project
 
 The `sfdx-project.json` file contains useful configuration information for your project. See [Salesforce DX Project Configuration](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_ws_config.htm) in the _Salesforce DX Developer Guide_ for details about this file.

package/dist/force-app/main/default/uiBundles/reactinternalapp/package.json

@@ -15,8 +15,8 @@
     "graphql:schema": "node scripts/get-graphql-schema.mjs"
   },
   "dependencies": {
-    "@salesforce/sdk-data": "^1.119.0",
-    "@salesforce/ui-bundle": "^1.119.0",
+    "@salesforce/sdk-data": "^1.119.2",
+    "@salesforce/ui-bundle": "^1.119.2",
     "@tailwindcss/vite": "^4.1.17",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -42,7 +42,7 @@
     "@graphql-eslint/eslint-plugin": "^4.1.0",
     "@graphql-tools/utils": "^11.0.0",
     "@playwright/test": "^1.49.0",
-    "@salesforce/vite-plugin-ui-bundle": "^1.119.0",
+    "@salesforce/vite-plugin-ui-bundle": "^1.119.2",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.1.0",
     "@testing-library/user-event": "^14.5.2",

package/dist/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@salesforce/webapp-template-base-sfdx-project-experimental",
-  "version": "1.119.0",
+  "version": "1.119.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@salesforce/webapp-template-base-sfdx-project-experimental",
-      "version": "1.119.0",
+      "version": "1.119.2",
       "license": "SEE LICENSE IN LICENSE.txt",
       "devDependencies": {
         "@lwc/eslint-plugin-lwc": "^3.3.0",

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/ui-bundle-template-base-sfdx-project",
-  "version": "1.119.0",
+  "version": "1.119.2",
   "description": "Base SFDX project template",
   "license": "SEE LICENSE IN LICENSE.txt",
   "publishConfig": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/ui-bundle-template-app-react-template-b2e",
-  "version": "1.119.0",
+  "version": "1.119.2",
   "description": "Salesforce React internal app template",
   "license": "SEE LICENSE IN LICENSE.txt",
   "author": "",