@salesforce/templates 66.7.6 → 66.7.8

package/lib/templates/project/reactexternalapp/scripts/{setup-cli.mjs → org-setup.mjs}

@@ -4,11 +4,11 @@
  * Use this script to make setup easier for each app generated from this template.
  *
  * Usage:
- *   node scripts/setup-cli.mjs --target-org <alias>           # interactive step picker (all selected)
- *   node scripts/setup-cli.mjs --target-org <alias> --yes     # skip picker, run all steps
- *   node scripts/setup-cli.mjs --target-org afv5 --skip-login
- *   node scripts/setup-cli.mjs --target-org afv5 --skip-data --skip-ui-bundle-build
- *   node scripts/setup-cli.mjs --target-org myorg --ui-bundle-name my-app
+ *   node scripts/org-setup.mjs --target-org <alias>           # interactive step picker (all selected)
+ *   node scripts/org-setup.mjs --target-org <alias> --yes     # skip picker, run all steps
+ *   node scripts/org-setup.mjs --target-org afv5 --skip-login
+ *   node scripts/org-setup.mjs --target-org afv5 --skip-data --skip-ui-bundle-build
+ *   node scripts/org-setup.mjs --target-org myorg --ui-bundle-name my-app
  *
  * Steps (in order):
  *   1. login     — sf org login web only if org not already connected (skip with --skip-login)
@@ -28,6 +28,32 @@ import { readdirSync, existsSync, readFileSync, writeFileSync, unlinkSync } from
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = resolve(__dirname, '..');
 
+/**
+ * npm strips .gitignore from published packages — generate them on first run.
+ * Templates are stored in scripts/gitignore-templates.json (generated at build
+ * time from the actual .gitignore files) so the content lives in one place.
+ * The JSON may not exist in git-cloned distributions where .gitignore is
+ * already present, so loading is best-effort.
+ */
+function loadGitignoreTemplates() {
+  const templatesPath = resolve(__dirname, 'gitignore-templates.json');
+  if (!existsSync(templatesPath)) return null;
+  try {
+    return JSON.parse(readFileSync(templatesPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function ensureGitignore(dir, content) {
+  if (!content) return;
+  const gitignorePath = resolve(dir, '.gitignore');
+  if (!existsSync(gitignorePath)) {
+    writeFileSync(gitignorePath, content, 'utf8');
+    console.log(`Created .gitignore in ${dir}`);
+  }
+}
+
 function resolveSfdxSource() {
   const sfdxPath = resolve(ROOT, 'sfdx-project.json');
   if (!existsSync(sfdxPath)) {
@@ -84,7 +110,7 @@ function parseArgs() {
 Setup CLI — one-command setup for apps in this project
 
 Usage:
-  node scripts/setup-cli.mjs --target-org <alias> [options]
+  node scripts/org-setup.mjs --target-org <alias> [options]
 
 Required:
   --target-org <alias>   Target Salesforce org alias (e.g. myorg)
@@ -292,6 +318,19 @@ function run(name, cmd, args, opts = {}) {
 }
 
 async function main() {
+  // Ensure .gitignore files exist (npm strips them from published packages).
+  const gitignoreTemplates = loadGitignoreTemplates();
+  if (gitignoreTemplates) {
+    ensureGitignore(ROOT, gitignoreTemplates.sfdx);
+    if (existsSync(UIBUNDLES_DIR)) {
+      for (const entry of readdirSync(UIBUNDLES_DIR, { withFileTypes: true })) {
+        if (entry.isDirectory() && !entry.name.startsWith('.')) {
+          ensureGitignore(resolve(UIBUNDLES_DIR, entry.name), gitignoreTemplates.webapp);
+        }
+      }
+    }
+  }
+
   const {
     targetOrg,
     uiBundleName,

package/lib/templates/project/reactexternalapp/scripts/sf-project-setup.mjs

@@ -10,11 +10,36 @@
 import { spawnSync } from 'node:child_process';
 import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { readdirSync, existsSync, readFileSync } from 'node:fs';
+import { readdirSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = resolve(__dirname, '..');
 
+/**
+ * npm strips .gitignore from published packages — generate them on first run.
+ * Templates are stored in scripts/gitignore-templates.json (generated at build
+ * time from the actual .gitignore files). The JSON may not exist in git-cloned
+ * distributions where .gitignore is already present, so loading is best-effort.
+ */
+function loadGitignoreTemplates() {
+  const templatesPath = resolve(__dirname, 'gitignore-templates.json');
+  if (!existsSync(templatesPath)) return null;
+  try {
+    return JSON.parse(readFileSync(templatesPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function ensureGitignore(dir, content) {
+  if (!content) return;
+  const gitignorePath = resolve(dir, '.gitignore');
+  if (!existsSync(gitignorePath)) {
+    writeFileSync(gitignorePath, content, 'utf8');
+    console.log(`Created .gitignore in ${dir}`);
+  }
+}
+
 function resolveUIBundlesDir() {
   const sfdxPath = resolve(ROOT, 'sfdx-project.json');
   if (!existsSync(sfdxPath)) {
@@ -56,6 +81,20 @@ function run(label, cmd, args, opts) {
   }
 }
 
+// Ensure .gitignore files exist (npm strips them from published packages).
+const gitignoreTemplates = loadGitignoreTemplates();
+if (gitignoreTemplates) {
+  ensureGitignore(ROOT, gitignoreTemplates.sfdx);
+  const bundlesDir = resolveUIBundlesDir();
+  if (existsSync(bundlesDir)) {
+    for (const entry of readdirSync(bundlesDir, { withFileTypes: true })) {
+      if (entry.isDirectory() && !entry.name.startsWith('.')) {
+        ensureGitignore(resolve(bundlesDir, entry.name), gitignoreTemplates.webapp);
+      }
+    }
+  }
+}
+
 const uiBundleDir = discoverUIBundleDir();
 console.log('SFDX project root:', ROOT);
 console.log('UI bundle directory:', uiBundleDir);

package/lib/templates/project/reactinternalapp/AGENT.md

@@ -19,7 +19,7 @@ Replace `<appName>` with the actual folder name found under `uiBundles/`. The so
 ├── sfdx-project.json
 ├── package.json                         # SFDX root scripts 
 ├── scripts/
-│   ├── setup-cli.mjs                    # One-command setup (deploy, schema, build)
+│   ├── org-setup.mjs                    # One-time org setup (deploy, schema, build)
 │   └── graphql-search.sh               # Schema entity lookup
 ├── config/
 │   └── project-scratch-def.json
@@ -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:
 
@@ -93,11 +93,13 @@ Used for SFDX metadata tooling. Scripts here target LWC/Aura, not the React app.
 | `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.
+**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-command setup:** `node scripts/setup-cli.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/lib/templates/project/reactinternalapp/CHANGELOG.md

@@ -3,6 +3,132 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [1.120.2](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.120.1...v1.120.2) (2026-04-01)
+
+**Note:** Version bump only for package @salesforce/ui-bundle-template-base-sfdx-project
+
+
+
+
+
+## [1.120.1](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.120.0...v1.120.1) (2026-04-01)
+
+**Note:** Version bump only for package @salesforce/ui-bundle-template-base-sfdx-project
+
+
+
+
+
+# [1.120.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.119.6...v1.120.0) (2026-04-01)
+
+**Note:** Version bump only for package @salesforce/ui-bundle-template-base-sfdx-project
+
+
+
+
+
+## [1.119.6](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.119.5...v1.119.6) (2026-04-01)
+
+**Note:** Version bump only for package @salesforce/ui-bundle-template-base-sfdx-project
+
+
+
+
+
+## [1.119.5](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.119.4...v1.119.5) (2026-03-31)
+
+**Note:** Version bump only for package @salesforce/ui-bundle-template-base-sfdx-project
+
+
+
+
+
+## [1.119.4](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.119.3...v1.119.4) (2026-03-31)
+
+
+### Bug Fixes
+
+* replace undefined WEBAPPLICATIONS_DIR with UIBUNDLES_DIR in org-setup ([#398](https://github.com/salesforce-experience-platform-emu/webapps/issues/398)) ([615d499](https://github.com/salesforce-experience-platform-emu/webapps/commit/615d49976fd4b92a840d25db79591e2818938a92))
+
+
+
+
+
+## [1.119.3](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.119.2...v1.119.3) (2026-03-31)
+
+**Note:** Version bump only for package @salesforce/ui-bundle-template-base-sfdx-project
+
+
+
+
+
+## [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
+
+
+
+
+
+## [1.118.4](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.118.3...v1.118.4) (2026-03-31)
+
+**Note:** Version bump only for package @salesforce/ui-bundle-template-base-sfdx-project
+
+
+
+
+
+## [1.118.3](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.118.2...v1.118.3) (2026-03-31)
+
+**Note:** Version bump only for package @salesforce/ui-bundle-template-base-sfdx-project
+
+
+
+
+
+## [1.118.2](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.118.1...v1.118.2) (2026-03-31)
+
+
+### Bug Fixes
+
+* (@W-21734559) addresses missing .gitignore within template apps for vibes welcome experience ([#383](https://github.com/salesforce-experience-platform-emu/webapps/issues/383)) ([b8a35cf](https://github.com/salesforce-experience-platform-emu/webapps/commit/b8a35cf5352c231ccaa0797df88e64ee1c20a02a))
+
+
+
+
+
+## [1.118.1](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.118.0...v1.118.1) (2026-03-31)
+
+**Note:** Version bump only for package @salesforce/ui-bundle-template-base-sfdx-project
+
+
+
+
+
+# [1.118.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.117.5...v1.118.0) (2026-03-30)
+
+**Note:** Version bump only for package @salesforce/ui-bundle-template-base-sfdx-project
+
+
+
+
+
 ## [1.117.5](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.117.4...v1.117.5) (2026-03-30)
 
 **Note:** Version bump only for package @salesforce/ui-bundle-template-base-sfdx-project

package/lib/templates/project/reactinternalapp/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/lib/templates/project/reactinternalapp/_p_/_m_/_w_/_a_/package.json

@@ -3,6 +3,9 @@
   "private": true,
   "version": "1.59.0",
   "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
   "scripts": {
     "dev": "vite",
     "dev:design": "vite --mode design",
@@ -15,8 +18,8 @@
     "graphql:schema": "node scripts/get-graphql-schema.mjs"
   },
   "dependencies": {
-    "@salesforce/sdk-data": "^1.117.5",
-    "@salesforce/ui-bundle": "^1.117.5",
+    "@salesforce/sdk-data": "^1.120.2",
+    "@salesforce/ui-bundle": "^1.120.2",
     "@tailwindcss/vite": "^4.1.17",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -42,7 +45,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.117.5",
+    "@salesforce/vite-plugin-ui-bundle": "^1.120.2",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.1.0",
     "@testing-library/user-event": "^14.5.2",

package/lib/templates/project/reactinternalapp/_p_/_m_/_w_/_a_/src/_f_/_os_/utils/filterUtils.ts

@@ -385,7 +385,16 @@ function buildSingleFilter<TFilter>(
 			if (!value) return null;
 			const searchFields = config?.searchFields ?? [];
 			if (searchFields.length === 0) return null;
-			const clauses = searchFields.map((f) => ({ [f]: { like: `%${value}%` } }) as TFilter);
+			// Supports dot-notation for relationship fields (e.g. "User__r.Name")
+			// by building nested filter objects: { User__r: { Name: { like: "%x%" } } }
+			const clauses = searchFields.map((f) => {
+				const parts = f.split(".");
+				let clause: Record<string, unknown> = { like: `%${value}%` };
+				for (let i = parts.length - 1; i >= 0; i--) {
+					clause = { [parts[i]]: clause };
+				}
+				return clause as TFilter;
+			});
 			if (clauses.length === 1) return clauses[0];
 			return { or: clauses } as TFilter;
 		}

package/lib/templates/project/reactinternalapp/_p_/_m_/_w_/_a_/src/components/AgentforceConversationClient.tsx

@@ -13,6 +13,38 @@ import type {
 } from "../types/conversation";
 
 const GLOBAL_HOST_ID = "agentforce-conversation-client-global-host";
+
+const DEFAULT_STYLE_TOKENS: NonNullable<AgentforceClientConfig["styleTokens"]> = {
+	containerBackground: "#fafafa",
+
+	headerBlockBackground: "#372949",
+	headerBlockTextColor: "#ffffff",
+	headerBlockIconColor: "#ffffff",
+	headerBlockBorderBottomColor: "#3b0764",
+	headerBlockFocusBorder: "#c4b5fd",
+
+	messageBlockInboundBackgroundColor: "#ffffff",
+	messageBlockInboundTextColor: "#1f2937",
+	messageBlockInboundBorder: "1px solid #e5e7eb",
+
+	messageBlockOutboundBackgroundColor: "#ede9fe",
+	messageBlockOutboundTextColor: "#1f2937",
+	messageBlockOutboundBorder: "1px solid #d8b4fe",
+
+	messageInputTextColor: "#1f2937",
+	messageInputTextBackgroundColor: "#ffffff",
+	messageInputFooterBorderColor: "#d1d5db",
+	messageInputFooterBorderFocusColor: "#9ca3af",
+	messageInputFocusShadow: "0 0 0 3px rgba(156, 163, 175, 0.25)",
+	messageInputFooterPlaceholderText: "#6b7280",
+
+	messageInputFooterSendButton: "#7e22ce",
+	messageInputFooterSendButtonHoverColor: "#6b21a8",
+	messageInputSendButtonIconColor: "#ffffff",
+	messageInputSendButtonDisabledColor: "#e5e7eb",
+	messageInputActionButtonFocusBorder: "#a855f7",
+	errorBlockBackground: "#fafafa",
+};
 const SINGLETON_KEY = "__agentforceConversationClientSingleton";
 
 interface AgentforceConversationClientSingleton {
@@ -55,6 +87,7 @@ function getDefaultEmbedOptions(): ResolvedEmbedOptions {
  */
 export function AgentforceConversationClient({
 	agentId,
+	agentLabel,
 	inline: inlineProp,
 	headerEnabled,
 	showHeaderIcon,
@@ -77,10 +110,11 @@ export function AgentforceConversationClient({
 
 		return {
 			...(agentId !== undefined && { agentId }),
-			...(styleTokens !== undefined && { styleTokens }),
+			...(agentLabel !== undefined && { agentLabel }),
+			styleTokens: { ...DEFAULT_STYLE_TOKENS, ...styleTokens },
 			renderingConfig,
 		};
-	}, [agentId, inlineProp, headerEnabled, showHeaderIcon, width, height, styleTokens]);
+	}, [agentId, agentLabel, inlineProp, headerEnabled, showHeaderIcon, width, height, styleTokens]);
 
 	const inline = normalizedAgentforceClientConfig?.renderingConfig?.mode === "inline";
 
@@ -88,7 +122,7 @@ export function AgentforceConversationClient({
 		if (!normalizedAgentforceClientConfig?.agentId) {
 			throw new Error(
 				"AgentforceConversationClient requires agentId. " +
-					"Pass flat props only (agentId, inline, headerEnabled, showHeaderIcon, width, height, styleTokens).",
+					"Pass flat props only (agentId, agentLabel, inline, headerEnabled, showHeaderIcon, width, height, styleTokens).",
 			);
 		}