@salesforce/templates 66.4.1 → 66.5.0

package/lib/templates/project/reactb2e/_r_/skills/webapp-features/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: webapp-features
+description: Search, describe, and install pre-built UI features (authentication, shadcn components, navigation, charts, search, GraphQL, Agentforce AI) into Salesforce webapps. Use this when the user wants to add functionality to a webapp, or when determining what salesforce-provided features are available — whether prompted by the user or on your own initiative. Always check for an existing feature before building from scratch.
+---
+
+# webapps-features-experimental CLI — Agent Reference
+
+**Always check for an existing feature before building something yourself.** This CLI installs pre-built, tested feature packages into Salesforce webapps. Features range from foundational UI component libraries (shadcn/ui with Button, Card, Input, Table, etc.) to full-stack application capabilities like authentication (login, registration, password flows, session management, and Apex backend classes), global search, navigation menus, data visualization charts, GraphQL integrations, and Agentforce AI conversation UIs. Each feature ships as a complete implementation — including React components, context providers, route guards, and any required Salesforce server-side code — that already handles platform-specific concerns like Salesforce API integration, session management, and SFDX metadata structure. Building these from scratch is error-prone and unnecessary when a feature exists. **If no existing feature is found, ask the user before proceeding with a custom implementation — a relevant feature may exist under a different name or keyword.**
+
+```
+npx @salesforce/webapps-features-experimental <command> [options]
+```
+
+## Workflow: Search Project → Search Features → Describe → Install
+
+**MANDATORY**: When the user asks to add ANY webapp functionality, follow this entire workflow. Do not skip steps.
+
+### 1. Search existing project code
+
+Before installing anything, check whether the functionality already exists in the **project source code** (not dependencies).
+
+- **Always scope searches to `src/`** to avoid matching files in `node_modules/`, `dist/`, or `build/` output
+- Use Glob with a scoped path: e.g., `src/**/Button.tsx`, `src/**/*auth*.tsx`
+- Use Grep with the `path` parameter set to the `src/` directory, or use `glob: "*.{ts,tsx}"` to restrict file types
+- Check common directories: `src/components/`, `src/lib/`, `src/pages/`, `src/hooks/`
+- **Never** search from the project root without a path or glob filter — this will crawl `node_modules` and produce massive, unhelpful output
+
+**If existing code is found** — read the files, present them to the user, and ask if they want to reuse or extend what's there. If yes, use the existing code and stop. If no, proceed to step 2.
+
+**If nothing is found** — proceed to step 2.
+
+### 2. Search available features
+
+```bash
+npx @salesforce/webapps-features-experimental list [options]
+```
+
+Options:
+
+- `-v, --verbose` — Show full descriptions, packages, and dependencies
+- `--search <query>` — Filter features by keyword (ranked by relevance)
+
+```bash
+npx @salesforce/webapps-features-experimental list
+npx @salesforce/webapps-features-experimental list --search "auth"
+npx @salesforce/webapps-features-experimental list --search "button"
+```
+
+**If no matching feature is found** — ask the user before proceeding with a custom implementation. A relevant feature may exist under a different name or keyword.
+
+### 3. Describe a feature
+
+```bash
+npx @salesforce/webapps-features-experimental describe <feature>
+```
+
+Shows description, package name, dependencies, components, copy operations, and example files.
+
+```bash
+npx @salesforce/webapps-features-experimental describe authentication
+npx @salesforce/webapps-features-experimental describe shadcn
+```
+
+### 4. Install a feature
+
+```bash
+npx @salesforce/webapps-features-experimental install <feature> --webapp-dir <path> [options]
+```
+
+Resolves the feature name to an npm package, installs it and its dependencies (including transitive feature dependencies like `shadcn`), copies source files into your project, and reports any `__example__` files that require manual integration.
+
+Options:
+
+- `--webapp-dir <name>` (required) — Webapp name, resolves to `<sfdx-source>/webapplications/<name>`
+- `--sfdx-source <path>` (default: `force-app/main/default`) — SFDX source directory
+- `--dry-run` (default: `false`) — Preview changes without writing files
+- `-v, --verbose` (default: `false`) — Enable verbose logging
+- `-y, --yes` (default: `false`) — Skip all prompts (auto-skip conflicts)
+- `--on-conflict <mode>` (default: `prompt`) — `prompt`, `error`, `skip`, or `overwrite`
+- `--conflict-resolution <file>` — Path to JSON file with per-file resolutions
+
+```bash
+# Install authentication (also installs shadcn dependency)
+npx @salesforce/webapps-features-experimental install authentication \
+  --webapp-dir mywebapp
+
+# Dry run to preview changes
+npx @salesforce/webapps-features-experimental install shadcn \
+  --webapp-dir mywebapp \
+  --dry-run
+
+# Non-interactive install (skip all file conflicts)
+npx @salesforce/webapps-features-experimental install authentication \
+  --webapp-dir mywebapp \
+  --yes
+```
+
+## Conflict Handling
+
+Since you are running in a non-interactive environment, you cannot use `--on-conflict prompt` directly. When conflicts are likely (e.g. installing into an existing project), you have two options:
+
+**Option A — Let the user resolve conflicts interactively.** Suggest the user run the install command themselves with `--on-conflict prompt` so they can decide per-file.
+
+**Option B — Two-pass automated resolution:**
+
+```bash
+# Pass 1: detect conflicts
+npx @salesforce/webapps-features-experimental install authentication \
+  --webapp-dir mywebapp \
+  --on-conflict error
+
+# The CLI will exit with an error listing every conflicting file path.
+
+# Pass 2: create a resolution file and re-run
+echo '{ "src/styles/global.css": "overwrite", "src/lib/utils.ts": "skip" }' > resolutions.json
+
+npx @salesforce/webapps-features-experimental install authentication \
+  --webapp-dir mywebapp \
+  --conflict-resolution resolutions.json
+```
+
+Resolution values per file: `"skip"` (keep existing) or `"overwrite"` (replace). When unsure how to resolve a conflict, ask the user rather than guessing.
+
+## Hint Placeholders in Copy Paths
+
+Some copy operations use **hint placeholders** in the `"to"` path — descriptive segments like `<desired-page-with-search-input>` that are NOT resolved by the CLI. These are guidance for the user or LLM to choose an appropriate destination.
+
+**How they work:** The file is copied with the literal placeholder name (e.g., `src/pages/<desired-page-with-search-input>.tsx`). After installation, you should:
+
+1. Read the copied file to understand its purpose
+2. Rename or relocate it to the intended target (e.g., `src/pages/Home.tsx`)
+3. Or integrate its patterns into an existing file, then delete it
+
+**How to identify them:** Hint placeholders use `<descriptive-name>` syntax but are NOT one of the system placeholders (`<sfdxSource>`, `<webappDir>`, `<webapp>`). They always appear in the middle or end of a path, never as the leading segment.
+
+**Example from features.json:**
+
+```json
+{
+  "to": "<webappDir>/src/pages/<desired-page-with-search-input>.tsx",
+  "description": "Example home page showing GlobalSearchInput integration",
+  "integrationTarget": "src/pages/Home.tsx"
+}
+```
+
+The `integrationTarget` field tells you the suggested destination. Use your judgment — if the user already has a different page where search should go, integrate there instead.
+
+**When `integrationTarget` itself is a placeholder:** Some features use a hint placeholder in the `integrationTarget` value (e.g., `"integrationTarget": "src/<path-to-desired-page-with-search-input>.tsx"`). This means there is no single default target — the user must decide which existing file to integrate into. When you encounter this:
+
+1. Ask the user which page or file they want to integrate the feature into
+2. Read the `__example__` file to understand the integration pattern
+3. Read the user's chosen target file
+4. Apply the pattern from the example into the target file
+
+## Post Installation: Integrating **example** Files
+
+Features may include `__example__` files (e.g., `__example__auth-app.tsx`) showing integration patterns.
+
+**The describe command shows**:
+
+- Which **example** files will be copied
+- Target file to integrate into (e.g., `src/app.tsx`)
+- What the example demonstrates
+
+### How to Integrate Example Files (CRITICAL FOR LLMs)
+
+⚠️ **ONLY USE Read AND Edit TOOLS - NO BASH COMMANDS** ⚠️
+
+**DO NOT DO THIS**:
+
+- ❌ `git status` or any git commands
+- ❌ `ls`, `cat`, `sed`, `awk`, or ANY bash file commands
+- ❌ Chaining bash commands to read multiple files
+- ❌ Using bash to check directories or file existence
+
+**DO THIS INSTEAD**:
+
+- ✅ Use Read tool with `file_path` parameter to read each file
+- ✅ Use Edit tool with `file_path`, `old_string`, `new_string` to modify files
+- ✅ That's it! Just Read and Edit tools.
+
+**Integration steps**:
+
+1. **Read each example file** (use Read tool)
+   - Example: Read tool with `file_path: "force-app/main/default/webapplications/mywebapp/src/__example__auth-app.tsx"`
+   - Note the imports and patterns to integrate
+
+2. **Read each target file** (use Read tool)
+   - Example: Read tool with `file_path: "force-app/main/default/webapplications/mywebapp/src/app.tsx"`
+   - Understand where the new code should go
+
+3. **Edit each target file** (use Edit tool)
+   - Add imports from the example
+   - Add or modify code following the example's patterns
+   - Preserve existing functionality
+
+4. **Delete the example file after successful integration** (use Bash tool)
+   - Example: `rm force-app/main/default/webapplications/mywebapp/src/__example__authentication-routes.tsx`
+   - Only delete after you have successfully integrated the pattern
+   - This keeps the codebase clean and removes temporary example files
+
+## Troubleshooting
+
+**Directory not found**: Check paths are correct, use absolute or correct relative paths
+
+**Feature not found**: Use `npx @salesforce/webapps-features-experimental list` to see available feature names
+
+**Conflicts in error mode**: Follow CLI instructions to create resolution file
+
+**Need help?**: Run `npx @salesforce/webapps-features-experimental --help` to see all commands and options

package/lib/templates/project/reactb2e/_r_/skills/{webapp-react-add-component → webapp-react}/SKILL.md

@@ -1,9 +1,11 @@
 ---
-name: webapp-react-add-component
-description: Creates React components, pages, headers, and footers using shadcn UI and Tailwind CSS. Use when the user asks to create a component, add a widget, build a UI element, add a page, create a new page, add a section (e.g. "add a contacts page"), add a header, add a footer, add a navigation bar, or add anything to the web application.
+name: webapp-react
+description: Use when editing any React code in the web application — creating or modifying components, pages, layout, headers, footers, or any TSX/JSX files. Follow this skill for add component, add page, header/footer, and general React UI implementation patterns (shadcn UI and Tailwind CSS).
 ---
 
-# Add React Component
+# React Web App (Components, Pages, Layout)
+
+Use this skill whenever you are editing React/TSX code in the web app (creating or modifying components, pages, header/footer, or layout).
 
 ## Step 1 — Identify the type of component
 

package/lib/templates/project/reactb2e/_r_/skills/{webapp-react-add-component → webapp-react}/implementation/header-footer.md

@@ -116,6 +116,14 @@ AppLayout (appLayout.tsx)
 - **Icons:** `lucide-react`; add `aria-hidden="true"` on decorative icons
 - **Design tokens:** `bg-background`, `text-foreground`, `text-muted-foreground`, `border`, `bg-primary`
 
+### Mobile hamburger / Menu icon — Must be functional
+
+If the header includes a hamburger or `Menu` icon for mobile:
+
+- **Do not** add a Menu/hamburger icon that does nothing. It must toggle a visible mobile menu.
+- **Required:** (1) State: `const [isOpen, setIsOpen] = useState(false)`. (2) Button: `onClick={() => setIsOpen(!isOpen)}`, `aria-label="Toggle menu"`. (3) Conditional panel: `{isOpen && ( <div>...nav links...</div> )}` with responsive visibility (e.g. `md:hidden`). (4) Close on navigate: each link in the panel should `onClick={() => setIsOpen(false)}`.
+- Implement in `appLayout.tsx` (or the component that owns the header). Use the `Menu` icon from `lucide-react`.
+
 ### Confirm — Header / Footer
 
 - Header and footer appear on every page (navigate to at least two routes)

package/lib/templates/project/{reactb2x/_r_/skills/webapp-react-add-component → reactb2e/_r_/skills/webapp-react}/implementation/page.md

@@ -2,13 +2,14 @@
 
 ### Rules
 
-1. **`routes.tsx` is the only route registry** — never add routes in `app.tsx` or inside page files.
-2. **All pages are children of the AppLayout route** — do not create top-level routes that bypass the layout shell.
-3. **Default export per page** — each page file has exactly one default-export component.
-4. **Path aliases in all imports** — use `@/pages/...`, `@/components/...`; no deep relative paths.
-5. **No inline styles** — Tailwind utility classes and design tokens only.
-6. **Catch-all last** — `path: '*'` (NotFound) must always remain the last child in the layout route.
-7. **Never modify `appLayout.tsx`** when adding a page — layout changes are a separate concern.
+1. **Edit the component that owns the UI, never output raw HTML** — When editing the home page or any page content, modify the actual `.tsx` file that renders the target. If the target is inside a child component (e.g. `<GlobalSearchInput />` in `Home.tsx`), edit the child's file (e.g. `GlobalSearchInput.tsx`), not the parent. Do not wrap the component with extra elements in the parent; go into the component and change its JSX. Do not paste or generate raw HTML.
+2. **`routes.tsx` is the only route registry** — never add routes in `app.tsx` or inside page files.
+3. **All pages are children of the AppLayout route** — do not create top-level routes that bypass the layout shell.
+4. **Default export per page** — each page file has exactly one default-export component.
+5. **Path aliases in all imports** — use `@/pages/...`, `@/components/...`; no deep relative paths.
+6. **No inline styles** — Tailwind utility classes and design tokens only.
+7. **Catch-all last** — `path: '*'` (NotFound) must always remain the last child in the layout route.
+8. **Never modify `appLayout.tsx`** when adding a page — layout changes are a separate concern.
 
 ### Step 1 — Create the page file
 

package/lib/templates/project/reactb2e/_r_/skills/webapp-ui-ux/SKILL.md

@@ -1,11 +1,13 @@
 ---
-name: ui-ux
-description: Comprehensive design guide for React + Tailwind + shadcn/ui applications. Searchable database with priority-based recommendations for styles, color palettes, font pairings, UX guidelines, and chart types.
+name: webapp-ui-ux
+description: Use when editing any UI code in the web application — styling, layout, design, appearance, Tailwind, shadcn, colors, typography, icons, or visual/UX changes. Comprehensive design guide and searchable database for React + Tailwind + shadcn/ui (styles, color palettes, font pairings, UX guidelines, chart types).
 ---
 
-# ui-ux
+# Web App UI/UX
 
-Comprehensive design guide for React + Tailwind + shadcn/ui applications. Contains 67 styles, 96 color palettes, 57 font pairings, 99 UX guidelines, and 25 chart types. Searchable database with priority-based recommendations.
+Use this skill whenever you are editing UI code in the web application — styling, layout, design, appearance, Tailwind, shadcn, colors, typography, icons, or any visual/UX change.
+
+Comprehensive design guide for React + Tailwind + shadcn/ui. Contains 67 styles, 96 color palettes, 57 font pairings, 99 UX guidelines, and 25 chart types. Searchable database with priority-based recommendations.
 
 ## Prerequisites
 
@@ -200,9 +202,10 @@ These are frequently overlooked issues that make UI look unprofessional:
 
 | Rule | Do | Don't |
 |------|----|----- |
-| **No emoji icons** | Use SVG icons (Heroicons, Lucide, Simple Icons) | Use emojis like 🎨 🚀 ⚙️ as UI icons |
+| **Icons: Lucide only** | Use **lucide-react** for all UI icons: `import { IconName } from 'lucide-react'` | Use Heroicons, react-icons, or other icon libraries; use emojis as icons |
+| **No emojis ever** | Use words + Lucide icons for labels, empty states, tooltips, headings | Use emojis anywhere in UI or user-facing text (e.g. 🎨 🚀 ⚙️) |
 | **Stable hover states** | Use color/opacity transitions on hover | Use scale transforms that shift layout |
-| **Correct brand logos** | Research official SVG from Simple Icons | Guess or use incorrect logo paths |
+| **Correct brand logos** | Research official SVG from Simple Icons (when needed outside Lucide) | Guess or use incorrect logo paths |
 | **Consistent icon sizing** | Use fixed viewBox (24x24) with w-6 h-6 | Mix different icon sizes randomly |
 
 ### Interaction & Cursor
@@ -237,8 +240,8 @@ These are frequently overlooked issues that make UI look unprofessional:
 Before delivering UI code, verify these items:
 
 ### Visual Quality
-- [ ] No emojis used as icons (use SVG instead)
-- [ ] All icons from consistent icon set (Heroicons/Lucide)
+- [ ] No emojis anywhere (UI, labels, empty states, tooltips—use words + Lucide icons only)
+- [ ] All icons from **lucide-react** only (no Heroicons, react-icons, or emojis)
 - [ ] Brand logos are correct (verified from Simple Icons)
 - [ ] Hover states don't cause layout shift
 - [ ] Use theme colors directly (bg-primary) not var() wrapper

package/lib/templates/project/reactb2e/_r_/webapp-cli-commands.md

@@ -0,0 +1,88 @@
+---
+description: CLI command generation rules — no node -e one-liners; safe quoting and scripts
+paths:
+  - "**/webapplications/**/*"
+---
+
+# A4D Enforcement: CLI Command Generation & No `node -e` One-Liners
+
+When **generating any CLI/shell commands** (for the user or for automation), follow the rules below. Default shell is **Zsh** (macOS); commands must work there without Bash-only syntax.
+
+---
+
+## 1. Never Use Complex `node -e` One-Liners
+
+**Forbidden:** `node -e` (or `node -p`, `node --eval`) for file manipulation, string replacement, reading/writing configs, or multi-line logic.
+
+**Why:** In Zsh, `node -e '...'` **silently breaks** due to:
+- **`!` (history expansion):** Zsh expands `!` in double-quoted strings → `event not found` or wrong output.
+- **Backticks:** `` ` `` is command substitution; the shell runs it before Node sees the string.
+- **Nested quoting:** Escaping differs between Bash and Zsh; multi-line JS in one string is fragile.
+
+**Allowed:** Trivial one-line only if it has **no** backticks, no `!`, no nested quotes, no multi-line, no `fs` usage. Example: `node -e "console.log(1+1)"`. If in doubt, **use a script file**.
+
+---
+
+## 2. How To Generate CLI Commands Correctly
+
+### Run Node scripts by path, not inline code
+
+- **Do:** `node scripts/setup-cli.mjs --target-org myorg`
+- **Do:** `node path/to/script.mjs arg1 arg2`
+- **Do not:** `node -e "require('fs').writeFileSync(...)"` or any non-trivial inline JS.
+
+### For file edits or transforms
+
+1. **Prefer IDE/agent file tools** (StrReplace, Write, etc.) — they avoid the shell.
+2. **Otherwise:** write a **temporary `.js` or `.mjs` file**, run it, then remove it. Use a **heredoc with quoted delimiter** so the shell does not interpret `$`, `` ` ``, or `!`:
+
+```bash
+cat > /tmp/_transform.js << 'SCRIPT'
+const fs = require('fs');
+const data = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+data.name = 'my-app';
+fs.writeFileSync('package.json', JSON.stringify(data, null, 2) + '\n');
+SCRIPT
+node /tmp/_transform.js && rm /tmp/_transform.js
+```
+
+3. **Simple replacements:** `sed -i '' 's/old/new/g' path/to/file` (macOS: `-i ''`).
+4. **JSON:** `jq '.name = "my-app"' package.json > tmp.json && mv tmp.json package.json`.
+
+### Quoting and shell safety
+
+- Use **single quotes** around the outer shell string when the inner content has `$`, `` ` ``, or `!`.
+- For heredocs that must be literal, use **`<< 'END'`** (quoted delimiter) so the body is not expanded.
+- **Do not** generate commands that rely on Bash-only features (e.g. `[[ ]]` is fine in Zsh; avoid `source` vs `.` if you need POSIX).
+
+### Paths and working directory
+
+- **State where to run from** when it matters, e.g. "From project root" or "From `force-app/main/default/webapplications/<appName>`".
+- Prefer **explicit paths** or `cd <dir> && ...` so the command is copy-paste safe.
+- This project: setup is `node scripts/setup-cli.mjs --target-org <alias>` from **project root**. Web app commands (`npm run dev`, `npm run build`, `npm run lint`) run from the **web app directory** (e.g. `force-app/main/default/webapplications/<appName>` or `**/webapplications/<appName>`).
+
+### npm / npx
+
+- Use **exact package names** (e.g. `npx @salesforce/webapps-features-experimental list`).
+- For app-specific scripts, **cd to the web app directory first**, then run `npm run <script>` or `npm install ...`.
+- Chain steps with `&&`; one logical command per line is clearer than one giant line.
+
+### Summary checklist when generating a command
+
+- [ ] No `node -e` / `node -p` / `node --eval` with complex or multi-line code.
+- [ ] If Node logic is needed, use `node path/to/script.mjs` or a temp script with heredoc `<< 'SCRIPT'`.
+- [ ] No unescaped `!`, `` ` ``, or `$` in double-quoted strings in Zsh.
+- [ ] Working directory and required args (e.g. `--target-org`) are clear.
+- [ ] Prefer file-editing tools over shell one-liners when editing project files.
+
+---
+
+## 3. Violation Handling
+
+- If a generated command used a complex `node -e` one-liner, **revert and redo** using a script file, `sed`/`jq`, or IDE file tools.
+- If the user sees `event not found`, `unexpected token`, or garbled output, **check for**:
+  - `node -e` with special characters,
+  - Double-quoted strings containing `!` or backticks,
+  - Wrong working directory or missing args.
+
+**Cross-reference:** **webapp.md** (MUST FOLLOW #1) summarizes the no–`node -e` rule; this file is the full reference for CLI command generation and alternatives.

package/lib/templates/project/reactb2e/_r_/webapp-react-code-quality.md

@@ -1,7 +1,7 @@
 ---
 description: Code quality and build validation standards
 paths:
-  - "force-app/main/default/webapplications/**/*"
+  - "**/webapplications/**/*"
 ---
 
 # Code Quality & Build Validation

package/lib/templates/project/reactb2e/_r_/webapp-react-typescript.md

@@ -1,7 +1,7 @@
 ---
 description: Strict TypeScript standards for type-safe React applications
 paths:
-  - "force-app/main/default/webapplications/**/*"
+  - "**/webapplications/**/*"
 ---
 
 # TypeScript Standards

package/lib/templates/project/reactb2e/_r_/webapp-react.md

@@ -1,7 +1,7 @@
 ---
 description: React-specific patterns and Salesforce data access for SFDX web apps
 paths:
-  - "force-app/main/default/webapplications/**/*"
+  - "**/webapplications/**/*"
 ---
 
 # React Web App (SFDX)
@@ -18,6 +18,15 @@ For layout, navigation, and generation rules, see **webapp.md**.
 - Dev server: `npm run dev`
 - Build: `npm run build`
 
+## Routing (React Router)
+
+Use a **single** router package for the app. When using `createBrowserRouter` and `RouterProvider` from `react-router`, all routing imports must come from **`react-router`** — not from `react-router-dom`.
+
+- ✅ `import { createBrowserRouter, RouterProvider, Link, useNavigate, useLocation, Outlet } from 'react-router';`
+- ❌ `import { Link } from 'react-router-dom';` when the app uses `RouterProvider` from `react-router`
+
+Mixing packages causes "Cannot destructure property 'basename' of ... as it is null" because `Link`/hooks from `react-router-dom` read a different context than the one provided by `RouterProvider` from `react-router`.
+
 ## Component Library (MANDATORY)
 
 Use **shadcn/ui** for UI components:
@@ -28,6 +37,42 @@ import { Card, CardHeader, CardContent } from '@/components/ui/card';
 import { Input } from '@/components/ui/input';
 ```
 
+## Icons & No Emojis (MANDATORY)
+
+- **Icons:** Use **lucide-react** only. Do not use Heroicons, Simple Icons, or other icon libraries in the web app.
+  - ✅ `import { Menu, Settings, Bell } from 'lucide-react';` then `<Menu className="w-5 h-5" />`
+  - ❌ Any emoji character as an icon or visual element (e.g. 🎨 🚀 ⚙️ 🔔)
+  - ❌ Other icon libraries (e.g. `@heroicons/react`, `react-icons`, custom SVG icon sets)
+- **No emojis ever:** Do not use emojis anywhere in the app: no emojis in UI labels, buttons, headings, empty states, tooltips, or any user-facing text. Use words and lucide-react icons instead.
+  - ✅ "Settings" with `<Settings />` icon
+  - ❌ "⚙️ Settings" or "Settings 🔧"
+- For icon usage patterns and naming, see the **webapp-ui-ux** skill (`.a4drules/skills/webapp-ui-ux/`, especially `data/icons.csv`).
+
+## Editing UI — Source Files Only (CRITICAL)
+
+When asked to edit the home page, a section, or any on-screen UI:
+
+- **Always edit the actual React/TSX source files.** Never output, paste, or generate raw HTML. The UI is built from components; the agent must locate the component file(s) that render the target area and change **JSX in those files**.
+- **Do not** replace JSX with HTML strings, and do not copy browser-rendered DOM (e.g. expanded `<div>`, `data-slot`, long class strings) into the codebase. That is the output of React + shadcn; the source is `.tsx` with `<Card>`, `<Input>`, etc.
+- **Edit inside the component that owns the UI.** If the element to change is rendered by a **child component** (e.g. `<GlobalSearchInput />` in `Home.tsx`), make the edit **inside that component's file** (e.g. `GlobalSearchInput.tsx`). Do **not** only wrap the component with extra elements in the parent (e.g. adding a `<section>` or `<div>` around `<GlobalSearchInput />`). The parent composes components; the visual/content change belongs in the component that actually renders that part of the UI.
+- **Where to edit:**
+  - **Home page content:** `src/pages/Home.tsx` — but if the target is inside a child (e.g. `<GlobalSearchInput />`), edit the child's file, not the parent.
+  - **Layout, header, nav:** `src/appLayout.tsx`.
+  - **Feature-specific UI (e.g. search, list):** open the **specific component file** that renders the target (e.g. `GlobalSearchInput.tsx` for the search input UI).
+- **Steps:** (1) Identify which **component** owns the section (follow the import: e.g. `GlobalSearchInput` → its file). (2) Open that component's file and modify the JSX there. (3) Only change the parent (e.g. `Home.tsx`) if the change is layout/ordering of components, not the internals of a child. Do not emit a standalone HTML snippet as the “edit.”
+
+## Mobile Nav / Hamburger — Must Be Functional
+
+When adding a navigation menu that includes a hamburger (or Menu icon) for mobile:
+
+- **Do not** add a hamburger/Menu icon that does nothing. The icon must **toggle a visible mobile menu**.
+- **Required implementation:**
+  1. **State:** e.g. `const [isOpen, setIsOpen] = useState(false);`
+  2. **Toggle button:** The hamburger/Menu button must have `onClick={() => setIsOpen(!isOpen)}` and `aria-label="Toggle menu"` (or equivalent).
+  3. **Conditional panel:** A mobile-only menu panel that renders when `isOpen` is true, e.g. `{isOpen && ( <div className="..."> ... nav links ... </div> )}`. Use responsive classes (e.g. `md:hidden`) so the panel is shown only on small screens if the desktop nav is separate.
+  4. **Close on navigation:** Each nav link in the mobile panel should call `onClick={() => setIsOpen(false)}` (or similar) so the menu closes when the user navigates.
+- Implement this in `appLayout.tsx` (or the component that owns the header/nav). See existing apps for the full pattern (state + button + conditional panel + link onClick).
+
 ## Styling
 
 - Use **Tailwind CSS** utility classes
@@ -137,11 +182,20 @@ window.location.reload();
 - ❌ Using LWC patterns (`@wire`, LDS) in React
 - ❌ Hardcoded Salesforce IDs or URLs
 - ❌ Missing error handling for async operations
+- ❌ Mixing `react-router` and `react-router-dom` (e.g. `RouterProvider` from `react-router` but `Link` from `react-router-dom`) — use one package for all routing imports
+- ❌ Using emojis anywhere in the app (labels, icons, empty states, headings, tooltips)
+- ❌ Using any icon library other than **lucide-react** (no Heroicons, react-icons, or emoji-as-icon)
+- ❌ Outputting or pasting raw HTML when editing UI — always edit the React/TSX source files (e.g. `Home.tsx`, `appLayout.tsx`, feature components)
+- ❌ Adding a hamburger or Menu icon for mobile nav without implementing toggle state, conditional menu panel, and close-on-navigate
 
 ## Quality Checklist
 
 - [ ] Entry point maintained (`app.tsx`)
 - [ ] Uses shadcn/ui and Tailwind
+- [ ] Icons from **lucide-react** only; no emojis anywhere in UI or user-facing text
+- [ ] UI changes made by editing .tsx source files (never by pasting raw HTML)
+- [ ] If mobile hamburger exists: it has toggle state, conditional menu panel, and close on link click
+- [ ] All routing imports from same package as router (e.g. `react-router` only)
 - [ ] DataSDK used for all Salesforce API calls
 - [ ] Proper error handling with try/catch
 - [ ] Loading and error states implemented

package/lib/templates/project/reactb2e/_r_/webapp-skills-first.md

@@ -1,7 +1,7 @@
 ---
 description: Always search for and read relevant skills before starting any task
 paths:
-  - "force-app/main/default/webapplications/**/*"
+  - "**/webapplications/**/*"
 ---
 
 # Skills-First Protocol (MUST FOLLOW)