@salesforce/webapp-template-base-sfdx-project-experimental 1.103.2

package/.a4drules/skills/webapp-csp-trusted-sites/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: webapp-csp-trusted-sites
+description: Creates Salesforce CSP Trusted Site metadata when adding external domains. Use when the user adds an external API, CDN, image host, font provider, map tile server, or any third-party URL that the web application needs to load resources from — or when a browser console shows a CSP violation error.
+---
+
+# CSP Trusted Sites
+
+## When to Use
+
+Use this skill whenever the application references a new external domain that is not already registered as a CSP Trusted Site. This includes:
+
+- Adding images from a new CDN (Unsplash, Pexels, Cloudinary, etc.)
+- Loading fonts from an external provider (Google Fonts, Adobe Fonts)
+- Calling a third-party API (Open-Meteo, Nominatim, Mapbox, etc.)
+- Loading map tiles from a tile server (OpenStreetMap, Mapbox)
+- Embedding iframes from external services (YouTube, Vimeo)
+- Loading external stylesheets or scripts
+
+Salesforce enforces Content Security Policy (CSP) headers on all web applications. Any external domain not registered as a CSP Trusted Site will be blocked by the browser, causing images to not load, API calls to fail, or fonts to be missing.
+
+**Reference:** [Salesforce CspTrustedSite Object Reference](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_csptrustedsite.htm)
+
+---
+
+## Step 1 — Identify external domains
+
+Scan the code for any URLs pointing to external domains. Common patterns:
+
+- `fetch("https://api.example.com/...")` — API calls
+- `<img src="https://images.example.com/..." />` — images
+- `<link href="https://fonts.example.com/..." />` — stylesheets
+- `url="https://tiles.example.com/{z}/{x}/{y}.png"` — map tiles
+- `@import url("https://cdn.example.com/...")` — CSS imports
+
+Extract the **origin** (scheme + host) from each URL. For example:
+- `https://api.open-meteo.com/v1/forecast?lat=...` → `https://api.open-meteo.com`
+- `https://images.unsplash.com/photo-123?w=800` → `https://images.unsplash.com`
+
+---
+
+## Step 2 — Check existing CSP Trusted Sites
+
+Before creating a new file, check if the domain already has a CSP Trusted Site:
+
+```bash
+ls force-app/main/default/cspTrustedSites/
+```
+
+If the domain is already registered, no action is needed.
+
+---
+
+## Step 3 — Determine the CSP directive(s)
+
+Map the resource type to the correct CSP `isApplicableTo*Src` fields. Read `implementation/metadata-format.md` for the full reference.
+
+Quick reference:
+
+| Resource type | CSP directive field(s) to set `true` |
+|--------------|--------------------------------------|
+| Images (img, background-image) | `isApplicableToImgSrc` |
+| API calls (fetch, XMLHttpRequest) | `isApplicableToConnectSrc` |
+| Fonts (.woff, .woff2, .ttf) | `isApplicableToFontSrc` |
+| Stylesheets (CSS) | `isApplicableToStyleSrc` |
+| Video / audio | `isApplicableToMediaSrc` |
+| Iframes | `isApplicableToFrameSrc` |
+
+**Always also set `isApplicableToConnectSrc` to `true`** — most resources also require connect-src for preflight/redirect handling.
+
+---
+
+## Step 4 — Create the metadata file
+
+Read `implementation/metadata-format.md` and follow the instructions to create the `.cspTrustedSite-meta.xml` file.
+
+---
+
+## Step 5 — Verify
+
+1. Confirm the file is valid XML and matches the expected schema.
+2. Confirm the file is placed in `force-app/main/default/cspTrustedSites/`.
+3. Confirm only the necessary `isApplicableTo*Src` fields are set to `true`.
+4. Run from the web app directory:
+
+```bash
+cd force-app/main/default/webapplications/<appName> && npm run lint && npm run build
+```
+
+- **Lint:** MUST result in 0 errors.
+- **Build:** MUST succeed.

package/.a4drules/skills/webapp-csp-trusted-sites/implementation/metadata-format.md

@@ -0,0 +1,281 @@
+# CSP Trusted Site Metadata — Implementation Guide
+
+## File location
+
+```
+force-app/main/default/cspTrustedSites/{Name}.cspTrustedSite-meta.xml
+```
+
+The `cspTrustedSites/` directory must be a direct child of `force-app/main/default/`. Create it if it does not exist.
+
+---
+
+## File naming convention
+
+The file name must match the `<fullName>` value inside the XML, with `.cspTrustedSite-meta.xml` appended.
+
+| Domain | fullName | File name |
+|--------|----------|-----------|
+| `https://images.unsplash.com` | `Unsplash_Images` | `Unsplash_Images.cspTrustedSite-meta.xml` |
+| `https://api.open-meteo.com` | `Open_Meteo_API` | `Open_Meteo_API.cspTrustedSite-meta.xml` |
+| `https://tile.openstreetmap.org` | `OpenStreetMap_Tiles` | `OpenStreetMap_Tiles.cspTrustedSite-meta.xml` |
+
+**Naming rules:**
+- Use PascalCase with underscores separating words (e.g. `Google_Fonts_Static`)
+- Name should describe the provider and resource type (e.g. `Pexels_Videos`, not just `Pexels`)
+- Must be unique across the org
+- Maximum 80 characters
+
+---
+
+## XML template
+
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+<CspTrustedSite xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>{UNIQUE_NAME}</fullName>
+    <description>{DESCRIPTION}</description>
+    <endpointUrl>{HTTPS_ORIGIN}</endpointUrl>
+    <isActive>true</isActive>
+    <context>All</context>
+    <isApplicableToConnectSrc>{true|false}</isApplicableToConnectSrc>
+    <isApplicableToFontSrc>{true|false}</isApplicableToFontSrc>
+    <isApplicableToFrameSrc>{true|false}</isApplicableToFrameSrc>
+    <isApplicableToImgSrc>{true|false}</isApplicableToImgSrc>
+    <isApplicableToMediaSrc>{true|false}</isApplicableToMediaSrc>
+    <isApplicableToStyleSrc>{true|false}</isApplicableToStyleSrc>
+</CspTrustedSite>
+```
+
+---
+
+## Field reference
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `fullName` | Yes | Unique API name. Must match the file name (before `.cspTrustedSite-meta.xml`). |
+| `description` | Yes | Human-readable purpose. Start with "Allow access to..." |
+| `endpointUrl` | Yes | The external origin (scheme + host). Must start with `https://`. No trailing slash. No path. |
+| `isActive` | Yes | Always `true` for new entries. Set `false` to disable without deleting. |
+| `context` | Yes | `All` (applies to all contexts). Other values: `LEX` (Lightning Experience only), `Communities` (Experience Cloud only), `VisualForce`. Use `All` unless there is a specific reason to restrict. |
+| `isApplicableToConnectSrc` | Yes | `true` if the domain is called via `fetch()`, `XMLHttpRequest`, or WebSocket. |
+| `isApplicableToFontSrc` | Yes | `true` if the domain serves font files (`.woff`, `.woff2`, `.ttf`, `.otf`). |
+| `isApplicableToFrameSrc` | Yes | `true` if the domain is loaded in an `<iframe>` or `<object>`. |
+| `isApplicableToImgSrc` | Yes | `true` if the domain serves images (`<img>`, CSS `background-image`, `<svg>`). |
+| `isApplicableToMediaSrc` | Yes | `true` if the domain serves audio or video (`<audio>`, `<video>`). |
+| `isApplicableToStyleSrc` | Yes | `true` if the domain serves CSS stylesheets (`<link rel="stylesheet">`). |
+
+**Reference:** [CspTrustedSite — Salesforce Object Reference](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_csptrustedsite.htm)
+
+---
+
+## CSP directive mapping
+
+| CSP header directive | Metadata field | What it allows |
+|---------------------|----------------|----------------|
+| `connect-src` | `isApplicableToConnectSrc` | `fetch()`, `XMLHttpRequest`, WebSocket, `EventSource` |
+| `font-src` | `isApplicableToFontSrc` | `@font-face` sources |
+| `frame-src` | `isApplicableToFrameSrc` | `<iframe>`, `<frame>`, `<object>`, `<embed>` |
+| `img-src` | `isApplicableToImgSrc` | `<img>`, `background-image`, `favicon`, `<picture>` |
+| `media-src` | `isApplicableToMediaSrc` | `<audio>`, `<video>`, `<source>`, `<track>` |
+| `style-src` | `isApplicableToStyleSrc` | `<link rel="stylesheet">`, `@import` in CSS |
+
+---
+
+## Common external domains and their directives
+
+Use this table as a quick reference when adding new domains:
+
+| Domain | connect-src | font-src | frame-src | img-src | media-src | style-src |
+|--------|:-----------:|:--------:|:---------:|:-------:|:---------:|:---------:|
+| `https://images.unsplash.com` | true | false | false | true | false | false |
+| `https://images.pexels.com` | true | false | false | true | false | false |
+| `https://videos.pexels.com` | true | false | false | false | true | false |
+| `https://fonts.googleapis.com` | true | false | false | false | false | true |
+| `https://fonts.gstatic.com` | true | true | false | false | false | false |
+| `https://avatars.githubusercontent.com` | true | false | false | true | false | false |
+| `https://api.open-meteo.com` | true | false | false | false | false | false |
+| `https://nominatim.openstreetmap.org` | true | false | false | false | false | false |
+| `https://tile.openstreetmap.org` | true | false | false | true | false | false |
+| `https://api.mapbox.com` | true | false | false | true | false | false |
+| `https://cdn.jsdelivr.net` | true | false | false | false | false | true |
+| `https://www.youtube.com` | false | false | true | true | false | false |
+| `https://player.vimeo.com` | false | false | true | false | false | false |
+| `https://res.cloudinary.com` | true | false | false | true | false | false |
+
+---
+
+## Complete examples
+
+### Image CDN (Unsplash)
+
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+<CspTrustedSite xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>Unsplash_Images</fullName>
+    <description>Allow access to Unsplash image content for static app media</description>
+    <endpointUrl>https://images.unsplash.com</endpointUrl>
+    <isActive>true</isActive>
+    <context>All</context>
+    <isApplicableToConnectSrc>true</isApplicableToConnectSrc>
+    <isApplicableToFontSrc>false</isApplicableToFontSrc>
+    <isApplicableToFrameSrc>false</isApplicableToFrameSrc>
+    <isApplicableToImgSrc>true</isApplicableToImgSrc>
+    <isApplicableToMediaSrc>false</isApplicableToMediaSrc>
+    <isApplicableToStyleSrc>false</isApplicableToStyleSrc>
+</CspTrustedSite>
+```
+
+### REST API (Open-Meteo weather)
+
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+<CspTrustedSite xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>Open_Meteo_API</fullName>
+    <description>Allow access to Open-Meteo weather forecast API</description>
+    <endpointUrl>https://api.open-meteo.com</endpointUrl>
+    <isActive>true</isActive>
+    <context>All</context>
+    <isApplicableToConnectSrc>true</isApplicableToConnectSrc>
+    <isApplicableToFontSrc>false</isApplicableToFontSrc>
+    <isApplicableToFrameSrc>false</isApplicableToFrameSrc>
+    <isApplicableToImgSrc>false</isApplicableToImgSrc>
+    <isApplicableToMediaSrc>false</isApplicableToMediaSrc>
+    <isApplicableToStyleSrc>false</isApplicableToStyleSrc>
+</CspTrustedSite>
+```
+
+### Font provider (Google Fonts — requires two entries)
+
+Google Fonts needs two CSP entries because CSS is served from `fonts.googleapis.com` and font files from `fonts.gstatic.com`:
+
+**Entry 1: Stylesheets**
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+<CspTrustedSite xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>Google_Fonts</fullName>
+    <description>Allow access to Google Fonts stylesheets for custom typography</description>
+    <endpointUrl>https://fonts.googleapis.com</endpointUrl>
+    <isActive>true</isActive>
+    <context>All</context>
+    <isApplicableToConnectSrc>true</isApplicableToConnectSrc>
+    <isApplicableToFontSrc>false</isApplicableToFontSrc>
+    <isApplicableToFrameSrc>false</isApplicableToFrameSrc>
+    <isApplicableToImgSrc>false</isApplicableToImgSrc>
+    <isApplicableToMediaSrc>false</isApplicableToMediaSrc>
+    <isApplicableToStyleSrc>true</isApplicableToStyleSrc>
+</CspTrustedSite>
+```
+
+**Entry 2: Font files**
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+<CspTrustedSite xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>Google_Fonts_Static</fullName>
+    <description>Allow access to Google Fonts static files for font loading</description>
+    <endpointUrl>https://fonts.gstatic.com</endpointUrl>
+    <isActive>true</isActive>
+    <context>All</context>
+    <isApplicableToConnectSrc>true</isApplicableToConnectSrc>
+    <isApplicableToFontSrc>true</isApplicableToFontSrc>
+    <isApplicableToFrameSrc>false</isApplicableToFrameSrc>
+    <isApplicableToImgSrc>false</isApplicableToImgSrc>
+    <isApplicableToMediaSrc>false</isApplicableToMediaSrc>
+    <isApplicableToStyleSrc>false</isApplicableToStyleSrc>
+</CspTrustedSite>
+```
+
+### Map tiles (OpenStreetMap)
+
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+<CspTrustedSite xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>OpenStreetMap_Tiles</fullName>
+    <description>Allow access to OpenStreetMap tile images for map rendering</description>
+    <endpointUrl>https://tile.openstreetmap.org</endpointUrl>
+    <isActive>true</isActive>
+    <context>All</context>
+    <isApplicableToConnectSrc>true</isApplicableToConnectSrc>
+    <isApplicableToFontSrc>false</isApplicableToFontSrc>
+    <isApplicableToFrameSrc>false</isApplicableToFrameSrc>
+    <isApplicableToImgSrc>true</isApplicableToImgSrc>
+    <isApplicableToMediaSrc>false</isApplicableToMediaSrc>
+    <isApplicableToStyleSrc>false</isApplicableToStyleSrc>
+</CspTrustedSite>
+```
+
+### Geocoding API (Nominatim)
+
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+<CspTrustedSite xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>OpenStreetMap_Nominatim</fullName>
+    <description>Allow access to OpenStreetMap Nominatim geocoding API</description>
+    <endpointUrl>https://nominatim.openstreetmap.org</endpointUrl>
+    <isActive>true</isActive>
+    <context>All</context>
+    <isApplicableToConnectSrc>true</isApplicableToConnectSrc>
+    <isApplicableToFontSrc>false</isApplicableToFontSrc>
+    <isApplicableToFrameSrc>false</isApplicableToFrameSrc>
+    <isApplicableToImgSrc>false</isApplicableToImgSrc>
+    <isApplicableToMediaSrc>false</isApplicableToMediaSrc>
+    <isApplicableToStyleSrc>false</isApplicableToStyleSrc>
+</CspTrustedSite>
+```
+
+---
+
+## Endpoint URL rules
+
+| Rule | Correct | Incorrect |
+|------|---------|-----------|
+| Must be HTTPS | `https://api.example.com` | `http://api.example.com` |
+| No trailing slash | `https://api.example.com` | `https://api.example.com/` |
+| No path | `https://api.example.com` | `https://api.example.com/v1/forecast` |
+| No port (unless non-standard) | `https://api.example.com` | `https://api.example.com:443` |
+| No wildcards | `https://api.example.com` | `https://*.example.com` |
+
+Each subdomain needs its own entry. For example, `fonts.googleapis.com` and `fonts.gstatic.com` are separate entries.
+
+---
+
+## When a service requires multiple domains
+
+Some services split resources across multiple subdomains. Create one CSP Trusted Site per domain:
+
+| Service | Domains needed |
+|---------|---------------|
+| Google Fonts | `fonts.googleapis.com` (CSS) + `fonts.gstatic.com` (font files) |
+| Mapbox | `api.mapbox.com` (tiles/API) + `events.mapbox.com` (telemetry) |
+| YouTube embed | `www.youtube.com` (iframe) + `i.ytimg.com` (thumbnails) |
+| Cloudflare CDN | `cdnjs.cloudflare.com` (scripts/CSS) |
+
+---
+
+## Troubleshooting CSP violations
+
+If the browser console shows a CSP error like:
+
+```
+Refused to load the image 'https://example.com/image.png' because it violates
+the following Content Security Policy directive: "img-src 'self' ..."
+```
+
+1. Extract the **blocked origin** from the URL (e.g. `https://example.com`).
+2. Identify the **directive** from the error message (e.g. `img-src` → `isApplicableToImgSrc`).
+3. Check if a CSP Trusted Site already exists for that origin.
+4. If not, create one using this skill.
+5. Deploy the metadata and refresh the page.
+
+---
+
+## Common mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Including a path in `endpointUrl` | Use only the origin: `https://api.example.com` |
+| Adding trailing slash | Remove it: `https://api.example.com` not `https://api.example.com/` |
+| Using HTTP instead of HTTPS | Salesforce requires HTTPS. If the service only supports HTTP, it cannot be added. |
+| Forgetting `isApplicableToConnectSrc` | Most resources also need connect-src for redirects/preflight. Set to `true` by default. |
+| One entry for multiple subdomains | Each subdomain needs its own file (e.g. `api.example.com` and `cdn.example.com` are separate) |
+| File name doesn't match `fullName` | They must be identical (excluding the `.cspTrustedSite-meta.xml` extension) |

package/.a4drules/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/.a4drules/skills/webapp-react/SKILL.md

@@ -0,0 +1,80 @@
+---
+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).
+---
+
+# 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
+
+Determine which of these three categories the request falls into, then follow the corresponding section below:
+
+- **Page** — user wants a new routed page (e.g. "add a contacts page", "create a dashboard page", "add a settings section")
+- **Header / Footer** — user wants a site-wide header, footer, nav bar, or page footer that appears on every page
+- **Component** — everything else: a widget, card, table, form, dialog, or other UI element placed within an existing page
+
+If it is not immediately clear from the user's message, ask:
+
+> "Are you looking to add a new page, a site-wide header or footer, or a component within an existing page?"
+
+Then follow the matching section.
+
+---
+
+## Clarifying Questions
+
+Ask **one question at a time** and wait for the response before asking the next. Stop when you have enough to build accurately — do not guess or assume.
+
+### For a Page
+
+1. **What is the name and purpose of the page?** (e.g., Contacts, Dashboard, Settings)
+2. **What URL path should it use?** (e.g., `/contacts`, `/dashboard`) — or derive from the page name?
+3. **Should the page appear in the navigation menu?**
+4. **Who can access it?** Public, authenticated users only (`PrivateRoute`), or unauthenticated only (e.g., login — `AuthenticationRoute`)?
+5. **What content or sections should the page include?** (list, form, table, detail view, etc.)
+6. **Does it need to fetch any data?** If so, from where?
+
+### For a Header / Footer
+
+1. **Header, footer, or both?**
+2. **What should the header contain?** (logo/app name, nav links, user avatar, CTA button, etc.)
+3. **What should the footer contain?** (copyright text, links, social icons, etc.)
+4. **Should the header be sticky (fixed to top while scrolling)?**
+5. **Is there a logo or brand name to display?** (or placeholder?)
+6. **Any specific color scheme or style direction?** (dark background, branded primary color, minimal, etc.)
+7. **Should navigation links appear in the header?** If so, which pages?
+
+### For a Component
+
+1. **What should the component do?** (display data, accept input, trigger an action, etc.)
+2. **What page or location should it appear on?**
+3. **Is this shared/reusable across pages, or specific to one feature?** (determines file location)
+4. **What data or props does it need?** (static content, props, fetched data)
+5. **Does it need internal state?** (loading, toggle, form state, etc.)
+6. **Are there any specific shadcn components to use?** (Card, Table, Dialog, Form, etc.)
+7. **Should it appear in a specific layout position?** (full-width, sidebar, inline, etc.)
+
+---
+
+## Implementation
+
+Once you have identified the type and gathered answers to the clarifying questions, read and follow the corresponding implementation guide:
+
+- **Page** — read `implementation/page.md` and follow the instructions there.
+- **Header / Footer** — read `implementation/header-footer.md` and follow the instructions there.
+- **Component** — read `implementation/component.md` and follow the instructions there.
+
+---
+
+## Verification
+
+Before completing, run from the web app directory `force-app/main/default/webapplications/<appName>/` (use the actual app folder name):
+
+```bash
+cd force-app/main/default/webapplications/<appName> && npm run lint && npm run build
+```
+
+- **Lint:** MUST result in 0 errors. Fix any ESLint or TypeScript issues.
+- **Build:** MUST succeed. Resolve any compilation or Vite build failures before finishing.