@salesforce/afv-skills 1.2.0 → 1.4.0

package/skills/creating-webapp/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: creating-webapp
+description: "Use this skill when creating or setting up a new SFDX React web application. Covers first steps, npm install, skills-first protocol, deployment order, and core web app rules."
+paths:
+  - "**/webapplications/**/*"
+---
+
+# First Steps (MUST FOLLOW)
+
+**Always run `npm install` before doing anything else** when working in a web app directory (e.g. `force-app/main/default/webapplications/<appName>/` or a dist app path). Dependencies must be installed before running `npm run dev`, `npm run build`, `npm run lint`, or any other script. If `node_modules` is missing or stale, commands will fail.
+
+# Skills-First (MUST FOLLOW)
+
+**Before writing any code or running any command**, search for relevant skills (`SKILL.md` files) that cover your task. Read the full skill and follow its instructions. Skills live in `.a4drules/skills/` and `feature/*/skills/`.
+
+- Do not write custom scripts or complex bash commands for a workflow already covered by a loaded skill.
+- Only proceed with manual execution after confirming no relevant skill exists.
+
+# Deployment Order (MUST FOLLOW)
+
+**Metadata deployments must complete before fetching GraphQL schema or running codegen.** The schema reflects the current org state; custom objects and fields appear only after metadata is deployed. Running schema fetch or codegen too early produces incomplete or incorrect types.
+
+**Invoke the `deploying-to-salesforce` skill** (`.a4drules/skills/deploying-to-salesforce/`) whenever the task involves:
+- Deploying metadata (objects, permission sets, layouts)
+- Fetching GraphQL schema (`npm run graphql:schema`)
+- Running GraphQL codegen (`npm run graphql:codegen`)
+- Generating deploy/setup commands or syncing with the org
+
+The skill enforces the correct sequence: **deploy metadata → assign permset → schema fetch → codegen**.
+
+**Critical rules:**
+- Do **not** run `npm run graphql:schema` before metadata (objects, permission sets) is deployed — the schema will not include custom objects/fields.
+- Do **not** skip schema refetch after any metadata deployment — re-run `npm run graphql:schema` and `npm run graphql:codegen` from the webapp dir.
+
+# Web App Generation
+
+## Before `sf webapp generate`
+
+**Webapp name (`-n`):** Must be **alphanumerical only**—no spaces, hyphens, underscores, or special characters. Use only letters (A–Z, a–z) and digits (0–9). Example: `CoffeeBoutique` not `Coffee Boutique`.
+
+```bash
+sf webapp generate -n MyWebApp -t reactbasic
+```
+
+Do not use `create-react-app`, Vite, or other generic scaffolds; use `sf webapp generate` so the app is SFDX-aware.
+
+## After Generation (MANDATORY)
+
+After generating or when touching an existing app:
+
+1. **Replace all default boilerplate** — "React App", "Vite + React", default `<title>`, placeholder text in shell. Use the actual app name.
+2. **Populate the home page** — Never leave it as default template. Add real content: landing section, banners, hero, navigation to features.
+3. **Update navigation and placeholders** — See [Navigation & Layout section](#navigation--layout-mandatory) below.
+
+# Navigation & Layout (MANDATORY)
+
+Agents consistently miss these. **You must not leave them default.**
+
+## appLayout.tsx is the Source of Truth
+
+- **Build navigation into the app layout** (`appLayout.tsx`). The layout must include nav (header, sidebar, or both) so every page shares the same shell.
+- Path: `force-app/main/default/webapplications/<appName>/src/appLayout.tsx`
+
+## When Making UI Changes
+
+**When making any change** that affects navigation, header, footer, sidebar, theme, or overall layout:
+
+1. **You MUST edit `src/appLayout.tsx`** (the layout used by `routes.tsx`).
+2. Do not only edit pages/components and leave `appLayout.tsx` unchanged.
+3. Before finishing: confirm you opened and modified `appLayout.tsx`. If you did not, the task is incomplete.
+
+## Navigation Menu (Critical)
+
+- **Always edit the navigation menu** in `appLayout.tsx`. Replace default nav items and labels with **app-specific** links and names.
+- Do **not** leave template items (e.g. "Home", "About", generic placeholder links).
+- Use real routes and labels matching the app (e.g. "Dashboard", "Products", "Orders").
+
+**Check before finishing:** Did I change the nav items and labels to match this app?
+
+## Placeholder Name & Design (Critical)
+
+- **Replace the placeholder app name** everywhere: header, nav brand/logo, footer, `<title>` in `index.html`, any "Welcome to…" text.
+- **Replace placeholder design** in the shell: default header/footer styling, generic branding.
+
+**Check before finishing:** Is the app name and shell design still the template default? If yes, update it.
+
+## Where to Edit
+
+
+| What                | Where                                                                |
+| ------------------- | -------------------------------------------------------------------- |
+| Layout/nav/branding | `force-app/main/default/webapplications/<appName>/src/appLayout.tsx` |
+| Document title      | `force-app/main/default/webapplications/<appName>/index.html`        |
+| Root page content   | Component at root route (often `Home` in `routes.tsx`)               |
+
+
+# React & TypeScript Constraints
+
+## Routing (React Router)
+
+Use a **single** router package. When using `createBrowserRouter` / `RouterProvider`, all imports MUST come from **`react-router`** — not `react-router-dom`.
+
+## Component Library + Styling
+
+- **shadcn/ui** for components: `import { Button } from '@/components/ui/button';`
+- **Tailwind CSS** utility classes
+
+## URL & Path Handling
+
+Apps run behind dynamic base paths. Router navigation (`<Link to>`, `navigate()`) prefer absolute paths (`/x`). Non-router attributes (`<img src>`) use dot-relative (`./x`) to resolve against `<base>`. Prefer Vite `import` for static assets.
+
+## Module Restrictions
+
+React apps must NOT import Salesforce platform modules like `lightning/*` or `@wire` (LWC-only). For data access, invoke the **using-salesforce-data** skill.
+
+# Frontend Aesthetics
+
+**Avoid AI slop.** Make creative, distinctive frontends:
+
+- **Typography:** Avoid Inter, Roboto, Arial, Space Grotesk as defaults. Choose distinctive fonts.
+- **Color:** Use cohesive color with sharp accents via CSS variables. Avoid purple-on-white clichés.
+- **Motion:** Use high-impact motion (e.g. staggered reveals).
+- **Depth:** Add atmosphere/depth in backgrounds.
+
+# Shell Command Safety (MUST FOLLOW)
+
+**Never use complex `node -e` one-liners** for file edits or multi-line transforms. They break in Zsh due to `!` history expansion and backtick interpolation. Use a temporary `.js` file, `sed`/`awk`, `jq`, or IDE file-editing tools instead.
+
+# Development Cycle
+
+- Execute tasks continuously until all planned items complete in the current iteration.
+- Maintain a running checklist and proceed sequentially.
+
+## Stop Conditions
+
+Only stop when:
+
+- All checklist items are completed and quality gates pass, or
+- A blocking error cannot be resolved after reasonable remediation, or
+- The user explicitly asks to pause.

package/skills/deploying-webapp-to-salesforce/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: deploying-webapp-to-salesforce
+description: "Enforces the correct order for deploying metadata, assigning permission sets, and fetching GraphQL schema. Use for ANY deployment to a Salesforce org — webapps, LWC, Aura, Apex, metadata, schema fetch, or org sync. Codifies setup-cli.mjs."
+---
+
+# Deploying to Salesforce
+
+Guidance for AI agents deploying metadata to a Salesforce org or syncing with the org. **The order of operations is critical.** This skill codifies the exact sequence from `scripts/setup-cli.mjs` and documents **every Salesforce interaction**.
+
+## When to Use
+
+Invoke this skill whenever the task involves:
+
+- Deploying metadata (objects, permission sets, layouts, Apex, web applications)
+- Generating deploy commands or setup instructions
+- Fetching the GraphQL schema (`npm run graphql:schema`)
+- Running GraphQL codegen (`npm run graphql:codegen`)
+- Full org setup (login, deploy, permset, data, schema, build)
+- Any manual step that touches the Salesforce org
+
+## Canonical Sequence (from setup-cli.mjs)
+
+Execute steps in this **exact order**. Steps marked **(SF)** perform a Salesforce API or CLI interaction.
+
+### Step 1: Login — org authentication
+
+| Action | Salesforce interaction? | Command |
+|--------|-------------------------|---------|
+| Check if org is connected | **(SF)** | `sf org display --target-org <alias> --json` |
+| If not connected: authenticate | **(SF)** | `sf org login web --alias <alias>` |
+
+- **Run when:** Org is not connected. **Omit when:** Org is already authenticated (check via `sf org display`).
+- All subsequent steps require an authenticated org.
+
+### Step 2: Webapp build — pre-deploy (required for entity deployment)
+
+| Action | Salesforce interaction? | Command |
+|--------|-------------------------|---------|
+| Install dependencies | No | `npm install` (in each webapp dir) |
+| Build web app | No | `npm run build` (in each webapp dir) |
+
+- Produces `dist/` so `sf project deploy start` can deploy web application entities. Run **before** deploy when deploying web apps.
+- **Run when:** Deploying web apps AND (`dist/` does not exist OR webapp source has changed since last build). **Omit when:** Not deploying, or `dist/` is current and no source changes.
+
+### Step 3: Deploy metadata
+
+| Action | Salesforce interaction? | Command |
+|--------|-------------------------|---------|
+| Deploy metadata | **(SF)** | See below |
+
+**Check for a manifest (package.xml) first.** Only use it if present:
+
+- **If `manifest/package.xml` (or `package.xml`) exists:** Deploy using the manifest:
+  ```bash
+  sf project deploy start --manifest manifest/package.xml --target-org <alias>
+  ```
+- **If no manifest exists:** Deploy all metadata from the project (packageDirectories in sfdx-project.json):
+  ```bash
+  sf project deploy start --target-org <alias>
+  ```
+
+Do not assume a manifest exists. Check the project root and common locations (e.g., `manifest/`, `config/`) before choosing the deploy command.
+
+- Deploys objects, layouts, permission sets, Apex classes, web applications, and all other metadata.
+- **Must complete successfully before schema fetch** — the schema reflects org state; custom objects/fields appear only after deployment.
+- **Run when:** Metadata has changed since last deploy, or never deployed. **Omit when:** No metadata changes and deploy has already run successfully.
+
+### Step 4: Post-deployment configuration — assign permissions and configure
+
+| Action | Salesforce interaction? | Command |
+|--------|-------------------------|---------|
+| Assign permission set or group | **(SF)** | `sf org assign permset --name <name> --target-org <alias>` (works for both permsets and permset groups) |
+| Assign profile to user | **(SF)** | `sf data update record` or at user creation |
+| Other post-deploy config | **(SF)** | Varies (e.g., named credentials, connected apps, custom settings) |
+
+**Example commands:**
+
+```bash
+# Permission set (assigns to default user of target org)
+sf org assign permset --name Property_Management_Access --target-org myorg
+
+# Permission set group (same command; pass the group name)
+sf org assign permset --name My_Permset_Group --target-org myorg
+
+# Assign to a specific user
+sf org assign permset --name Property_Management_Access --target-org myorg --on-behalf-of user@example.com
+
+# Profile — update existing user's profile (requires ProfileId and User Id)
+sf data update record --sobject User --record-id <userId> --values "ProfileId=<profileId>" --target-org myorg
+
+# Profile — get ProfileId first
+sf data query --query "SELECT Id, Name FROM Profile WHERE Name='Standard User'" --target-org myorg
+```
+
+- **Deploying does not mean assigning.** Even after permission sets, permission set groups, and profiles are deployed to the org, they must be explicitly assigned or configured for users. Deployment makes them available; assignment/configuration grants access.
+- **Permission sets** — Assign to users so they have access to custom objects and fields. Required for GraphQL introspection to return the correct schema.
+- **Permission set groups** — Assign to users when using grouped permission sets.
+- **Profiles** — Ensure users have the correct profile; profile assignment may be done at user creation or via Setup.
+- **Other post-deploy configuration** — Named credentials, connected apps, custom settings, flow activation, and any metadata that requires manual configuration after deploy.
+- All of the above must exist in the org (deployed in Step 3).
+- **Run when:** Any permission set, permission set group, profile, or other post-deploy config was deployed or changed and not yet assigned/configured. **Omit when:** All required assignments and configuration are already in place.
+
+**Proactive behavior:** After a successful deploy, discover permission sets in the project (e.g., `force-app/main/default/permissionsets/*.permissionset-meta.xml`) and assign each one. Extract the API name from the filename (e.g., `Property_Management_Access.permissionset-meta.xml` → `Property_Management_Access`). If the user has not explicitly requested a full setup, you may ask: "Do you want me to assign the permission sets to your org?" — but do not skip this step silently; either run it or ask.
+
+### Step 5: Data — prepare and import (optional)
+
+| Action | Salesforce interaction? | Command |
+|--------|-------------------------|---------|
+| Prepare unique fields | No | `node scripts/prepare-import-unique-fields.js --data-dir <dataDir>` |
+| Clean existing records | **(SF)** | `sf apex run --target-org <alias> --file <apex>` (per sobject, reverse plan order) |
+| Import records | **(SF)** | `sf apex run --target-org <alias> --file <apex>` (per batch) |
+
+- Only runs if `data/data-plan.json` and `data/` exist.
+- Delete runs in reverse plan order (children before parents).
+- Import uses Anonymous Apex with `Database.DMLOptions.duplicateRuleHeader.allowSave = true`.
+- **Run when:** Data plan exists AND (never imported OR data files or plan changed). **Omit when:** No data plan, or data already imported and unchanged.
+
+**Proactive behavior:** If `data/data-plan.json` and `data/` exist, you MUST ask the user: "Do you want me to import the sample data now? This will prepare unique fields, optionally clean existing records, and import data. Reply yes to proceed." Do not skip this step silently; either run it (after confirmation) or ask. Never import or clean without explicit user confirmation.
+
+### Step 6: GraphQL schema and codegen
+
+| Action | Salesforce interaction? | Command |
+|--------|-------------------------|---------|
+| Install webapp deps | No | `npm install` (in webapp dir) |
+| Set default org | **(SF)** | `sf config set target-org <alias> --global` |
+| Fetch schema (introspection) | **(SF)** | `npm run graphql:schema` (from webapp dir) |
+| Generate types | No | `npm run graphql:codegen` (from webapp dir) |
+
+- `graphql:schema` performs GraphQL introspection against the org — a **Salesforce API call**.
+- Schema is written to `schema.graphql` at the SFDX project root.
+- Codegen reads the schema file locally; no Salesforce interaction.
+- **Run when:** Schema does not exist, OR metadata was deployed/changed since last schema fetch, OR permissions or post-deploy config was assigned since last schema fetch. **Omit when:** Schema exists and is current relative to org state.
+
+### Step 7: Webapp build (if not done in Step 2)
+
+| Action | Salesforce interaction? | Command |
+|--------|-------------------------|---------|
+| Build web app | No | `npm run build` (in webapp dir) |
+
+- **Run when:** Build is needed (e.g., for dev server or deploy) AND (`dist/` does not exist OR webapp source has changed since last build). **Omit when:** `dist/` is current and no build needed.
+
+### Step 8: Dev server (optional)
+
+| Action | Salesforce interaction? | Command |
+|--------|-------------------------|---------|
+| Launch dev server | No | `npm run dev` (in webapp dir) |
+
+- **Run when:** User requests to launch the dev server. **Omit when:** Not requested.
+
+## Summary: All Salesforce Interactions (in order)
+
+1. `sf org display` — check org connection
+2. `sf org login web` — authenticate (if needed)
+3. `sf project deploy start` — deploy metadata
+4. `sf org assign permset` (permsets and permset groups) / profile assignment / other post-deploy config — assign permissions and configure
+5. `sf apex run` — delete existing data (if data plan)
+6. `sf apex run` — import data (if data plan)
+7. `sf config set target-org` — set default org for schema
+8. `npm run graphql:schema` — GraphQL introspection (Salesforce API)
+
+## Post-Deploy Checklist (MUST NOT SKIP)
+
+After **every successful metadata deploy**, the agent MUST address these before considering the task complete:
+
+1. **Permission sets** — Discover `force-app/main/default/permissionsets/*.permissionset-meta.xml`, extract API names, and assign each via `sf org assign permset --name <name> --target-org <alias>`. If unsure, ask: "Do you want me to assign the permission sets (e.g., Property_Management_Access, Tenant_Maintenance_Access) to your org?"
+2. **Data import** — If `data/data-plan.json` exists, ask: "Do you want me to import the sample data now? Reply yes to proceed." Do not import without confirmation.
+3. **Schema refetch** — Run `npm run graphql:schema` and `npm run graphql:codegen` from the webapp dir (required after deploy).
+
+Do not silently skip permission set assignment or data import. Either run them or ask the user.
+
+## Agent Decision Criteria
+
+Evaluate each step before running it. Ask:
+
+- **Has this step ever run before?** If not, it is likely needed.
+- **Have changes been made that require this step?** (e.g., metadata edits → deploy; deploy → schema refetch)
+- **Is the current state sufficient?** (e.g., org connected, schema exists and is current, permissions and post-deploy config assigned)
+
+Do not rely on CLI flags. Decide based on project state and what has changed.
+
+## Evaluation: When Each Step Touches Salesforce
+
+| Step | Salesforce interaction | Run when |
+|------|------------------------|----------|
+| 1. Login | Yes | Org not connected |
+| 2. Webapp build | No | Deploying web apps AND dist missing or source changed |
+| 3. Deploy | Yes | Metadata changed or never deployed |
+| 4. Post-deploy config | Yes | Permission sets, permset groups, profiles, or other config deployed/changed and not assigned |
+| 5. Data | Yes | Data plan exists AND (never imported OR data changed) |
+| 6. GraphQL | Yes (schema only) | Schema missing or metadata/permissions changed since last fetch |
+| 7. Webapp build | No | Build needed AND dist missing or source changed |
+| 8. Dev | No | User requests dev server |
+
+**Critical rule:** Steps 3 (deploy) and 4 (post-deploy config) must complete **before** step 6 (graphql:schema). The schema reflects the org state; running introspection too early yields an incomplete schema.
+
+## Schema Refetch Rule (CRITICAL)
+
+**After any metadata deployment**, you MUST re-run schema fetch and codegen:
+
+- New custom objects
+- New custom fields
+- New or updated permission sets
+- Any change to metadata that affects the GraphQL schema
+
+```bash
+# From webapp dir (force-app/main/default/webapplications/<appName>/)
+npm run graphql:schema
+npm run graphql:codegen
+```
+
+Do **not** assume the existing `schema.graphql` is current after metadata changes.
+
+## One-Command Setup (Reference)
+
+The project includes `scripts/setup-cli.mjs` which runs this sequence in batch. Use it when the user wants a full setup; otherwise, follow this skill and run only the steps that are needed based on current state.
+
+## Prohibited Actions
+
+- **Do not** run `npm run graphql:schema` before metadata is deployed — the schema will not include custom objects/fields
+- **Do not** skip schema refetch after deploying new metadata — types and queries will be out of sync
+- **Do not** assign permissions or configure before deploying — permission sets, permset groups, and profiles must exist in the org first
+- **Do not** run GraphQL introspection before assigning permissions — the user may lack FLS for custom fields
+
+## Related Skills
+
+- **using-salesforce-data** — Full data access workflow (GraphQL queries/mutations, REST APIs, schema exploration, webapp integration)

package/skills/{salesforce-custom-application → generating-custom-application}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: salesforce-custom-application
-description: Use this skill when users need to create or configure Salesforce Custom Applications. Trigger when users mention custom apps, application metadata, app navigation, or organizing tabs into applications. Use when users want to create app containers for tabs and pages. Always use this skill for custom application work.
+name: generating-custom-application
+description: "Use this skill when users need to create or configure Salesforce Custom Applications. Trigger when users mention custom apps, application metadata, app navigation, or organizing tabs into applications. Use when users want to create app containers for tabs and pages. Always use this skill for custom application work."
 ---
 
 ## When to Use This Skill
@@ -11,7 +11,6 @@ Use this skill when you need to:
 - Configure application navigation and branding
 - Set up custom page layouts for objects
 - Troubleshoot deployment errors related to custom applications
-
 # CustomApplication (Lightning App) Metadata Specification
 
 ## Overview

package/skills/{salesforce-custom-field → generating-custom-field}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: salesforce-custom-field
-description: Use this skill when users need to create, generate, or validate Salesforce Custom Field metadata. Trigger when users mention custom fields, field types, Roll-up Summary fields, Master-Detail relationships, Lookup relationships, formula fields, picklists, or field metadata. Also use when users encounter field deployment errors, especially around Roll-up Summary format, Master-Detail constraints, or formula issues. Always use this skill for any custom field metadata work, field generation, or field troubleshooting.
+name: generating-custom-field
+description: "Use this skill when users need to create, generate, or validate Salesforce Custom Field metadata. Trigger when users mention custom fields, field types, Roll-up Summary fields, Master-Detail relationships, Lookup relationships, formula fields, picklists, or field metadata. Also use when users encounter field deployment errors, especially around Roll-up Summary format, Master-Detail constraints, or formula issues. Always use this skill for any custom field metadata work, field generation, or field troubleshooting."
 ---
 
 ## When to Use This Skill

package/skills/{salesforce-custom-lightning-type → generating-custom-lightning-type}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: salesforce-custom-lightning-type
-description: Use this skill when users need to create Custom Lightning Types (CLTs) for Einstein Agent actions or structured input/output schemas. Trigger when users mention CLT, Custom Lightning Types, JSON schemas for agents, type definitions, lightning__objectType, or editor/renderer configurations. This is complex - always use this skill for CLT work.
+name: generating-custom-lightning-type
+description: "Use this skill when users need to create Custom Lightning Types (CLTs) for Einstein Agent actions or structured input/output schemas. Trigger when users mention CLT, Custom Lightning Types, JSON schemas for agents, type definitions, lightning__objectType, or editor/renderer configurations. This is complex - always use this skill for CLT work."
 ---
 
 ## When to Use This Skill
@@ -103,9 +103,11 @@ When strict validation is enabled (`unevaluatedProperties: false`), keep each pr
      - Top-level `editor` object.
      - Use `editor.componentOverrides` for component overrides.
      - Use `editor.layout` for layout.
+     - **DEPRECATED**: Do NOT use `propertyRenderers` or `view` — these are legacy keys. Always use `componentOverrides` and `layout` instead.
    - **Root override pattern** (most common for fully custom editing UI):
      - `editor.componentOverrides["$"] = { "definition": "c/<yourEditorComponent>", "attributes": { ... } }`
      - When passing schema data into a custom LWC, use attribute mapping with the `{!$attrs.<name>}` syntax: e.g. `"attributes": { "myField": "{!$attrs.value}" }` so the runtime binds schema values to your component's attributes.
+     - **CRITICAL**: The `<name>` in `{!$attrs.<name>}` must be a property defined in your type schema. For example, if your schema has a property called `temperature`, use `{!$attrs.temperature}`, not `{!$attrs.value}` unless `value` is an actual property.
    - **Property-level override pattern** (for individual fields):
      - `editor.componentOverrides["<propertyName>"] = { "definition": "es_property_editors/<...>" }`
      - **Valid editor components** (examples): `es_property_editors/inputText`, `es_property_editors/inputNumber`, `es_property_editors/inputRichText`, `es_property_editors/inputImage`, `es_property_editors/inputTextarea`. **Do not use** `es_property_editors/inputList`.
@@ -113,6 +115,7 @@ When strict validation is enabled (`unevaluatedProperties: false`), keep each pr
    - **Layout pattern**:
      - `editor.layout.definition = "lightning/verticalLayout"`
      - `editor.layout.children[*].definition = "lightning/propertyLayout"` with `attributes.property = "<propertyName>"`
+     - **CRITICAL**: `lightning/propertyLayout` only accepts the `property` attribute. Do NOT add `label`, `title`, or any other attributes — these will fail validation with `additionalProperties: false` errors.
    - **Avoid known-invalid patterns**:
      - Do not use `es_property_editors/inputList`.
      - Do not use `itemSchema` attributes.
@@ -121,18 +124,41 @@ When strict validation is enabled (`unevaluatedProperties: false`), keep each pr
      - Top-level `renderer` object.
      - Use `renderer.componentOverrides` for component overrides.
      - Use `renderer.layout` for layout.
+     - **DEPRECATED**: Do NOT use `propertyRenderers` or `view` — these are legacy keys. Always use `componentOverrides` and `layout` instead.
    - **Root override pattern** (most common for fully custom rendering UI):
      - `renderer.componentOverrides["$"] = { "definition": "c/<yourRendererComponent>", "attributes": { ... } }`
      - Use `{!$attrs.<name>}` in attribute mappings when binding schema data to custom renderer component attributes.
+     - **CRITICAL**: Attribute mappings like `{!$attrs.propertyName}` must reference properties that **actually exist** in your type schema. Referencing non-existent properties will fail validation.
+     - **Type matching**: Attribute values must match the expected type for the component. For example, if a component expects a string attribute, passing an integer will fail validation.
    - **Property-level override pattern**:
      - `renderer.componentOverrides["<propertyName>"] = { "definition": "es_property_editors/outputText" | "es_property_editors/outputNumber" | "es_property_editors/outputImage" | ... }`. **Valid renderer components** (examples): `es_property_editors/outputText`, `es_property_editors/outputNumber`, `es_property_editors/outputImage`. Avoid input-style components in the renderer.
+   - **Layout pattern for renderer**:
+     - `renderer.layout.definition = "lightning/verticalLayout"`
+     - `renderer.layout.children[*].definition = "lightning/propertyLayout"` with `attributes.property = "<propertyName>"`
+     - **CRITICAL**: Same as editor layouts, `lightning/propertyLayout` only accepts the `property` attribute. Do NOT add `label`, `title`, or any other attributes.
    - **Collection renderer** (for root-level `lightning__listType` properties): Use `collection.renderer.componentOverrides["$"] = { "definition": "c/<yourListRendererComponent>" }` or `es_property_editors/genericListTypeRenderer` to render the list.
 5. **Place files in the correct bundle structure**
    - `lightningTypes/<TypeName>/schema.json`
    - (Optional) `lightningTypes/<TypeName>/lightningDesktopGenAi/editor.json`
    - (Optional) `lightningTypes/<TypeName>/lightningDesktopGenAi/renderer.json`
    - For Gen AI / Copilot the standard path is `lightningDesktopGenAi/`. Other targets (e.g. Experience Builder, Mobile Copilot, Enhanced Web Chat) use different subfolders when supported: `experienceBuilder/`, `lightningMobileGenAi/`, `enhancedWebChat/`.
-6. **Deploy and validate**
+6. **Configure custom LWC components (if using custom components)**
+   - **CRITICAL**: Custom LWC components referenced in editor/renderer configs MUST have the correct target configuration in their `-meta.xml` files:
+     - **For editor components** (`c/<componentName>` used in `editor.json`): The LWC's `-meta.xml` file must include `<target>lightning__AgentforceInput</target>`
+     - **For renderer components** (`c/<componentName>` used in `renderer.json`): The LWC's `-meta.xml` file must include `<target>lightning__AgentforceOutput</target>`
+   - Without the correct target, deployment will fail with: `Invalid target configuration. To use 'c/componentName' as a renderer/editor, your js-meta.xml file must include valid target 'lightning__AgentforceOutput/Input'.`
+   - Example `-meta.xml` for a renderer component:
+     ```xml
+     <?xml version="1.0" encoding="UTF-8"?>
+     <LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
+         <apiVersion>60.0</apiVersion>
+         <isExposed>true</isExposed>
+         <targets>
+             <target>lightning__AgentforceOutput</target>
+         </targets>
+     </LightningComponentBundle>
+     ```
+7. **Deploy and validate**
    - Deploy the bundle using your org's standard metadata deployment flow (e.g. Salesforce CLI or IDE). The MCP client or tooling in use should provide or integrate with the appropriate deploy/retrieve commands for Lightning Type bundles.
    - Validate incrementally: if deployment fails, remove disallowed keywords first (especially `examples`, `items`, nested `lightning:type`).
 
@@ -144,6 +170,11 @@ When strict validation is enabled (`unevaluatedProperties: false`), keep each pr
 | Array property rejected | Use of `items` (or `lightning:type` in nested arrays) rejected by validator | For nested arrays: keep only `type: "array"`. For root arrays: use minimal structure; remove `items` if rejected |
 | Apex-based CLT rejected | Extra fields added (e.g., `type`, `properties`) | Use only `title`, optional `description`, and `lightning:type` |
 | Editor config rejected | Use of invalid patterns (`es_property_editors/inputList`, `itemSchema`) or unrecognized top-level keys | Use `editor.componentOverrides` and `editor.layout`; keep config minimal |
+| `additionalProperties` error on layout attributes | Adding `label` or other attributes to `lightning/propertyLayout` | Only use `property` attribute in `lightning/propertyLayout`. Remove `label`, `title`, or any other attributes |
+| Invalid target configuration for custom LWC | Custom LWC component's `-meta.xml` missing required target (`lightning__AgentforceInput` or `lightning__AgentforceOutput`) | Add correct target to LWC's `-meta.xml`: use `lightning__AgentforceInput` for editors, `lightning__AgentforceOutput` for renderers |
+| Attribute mapping doesn't exist in type schema | Using `{!$attrs.propertyName}` where `propertyName` is not defined in schema | Ensure all attribute mappings reference actual properties in your type schema's `properties` section |
+| `additionalProperties` error with deprecated keys | Using `propertyRenderers` or `view` in editor/renderer config | Replace deprecated `propertyRenderers` with `componentOverrides` and `view` with `layout` |
+| Type mismatch in component attributes | Passing wrong type for component attribute (e.g., integer instead of string) | Ensure attribute values match the expected type defined by the component |
 
 ## Verification Checklist
 - [ ] Root schema has `type: "object"`, `title`, `lightning:type: "lightning__objectType"`, and `unevaluatedProperties: false`
@@ -155,3 +186,6 @@ When strict validation is enabled (`unevaluatedProperties: false`), keep each pr
 - [ ] Bundle structure and filenames match Lightning Types requirements
 - [ ] Editor config uses only allowed patterns (no `es_property_editors/inputList`, no `itemSchema`); use valid components (e.g. `es_property_editors/inputText`, `es_property_editors/inputNumber`) or custom `c/` components
 - [ ] Renderer config uses output-style components (e.g. `es_property_editors/outputText`, `es_property_editors/outputNumber`) where applicable, not input editors
+- [ ] Layout configurations use `lightning/propertyLayout` with ONLY the `property` attribute (no `label`, `title`, or other attributes)
+- [ ] All attribute mappings (`{!$attrs.propertyName}`) reference properties that exist in the type schema
+- [ ] Custom LWC components have correct targets in `-meta.xml`: `lightning__AgentforceInput` for editors, `lightning__AgentforceOutput` for renderers

package/skills/{salesforce-custom-object → generating-custom-object}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: salesforce-custom-object
-description: Use this skill when users need to create, generate, or validate Salesforce Custom Object metadata. Trigger when users mention custom objects, creating objects, object metadata, .object files, sharing models, name fields, or validation rules on objects. Also use when users say things like "create a custom object", "generate object metadata", "set up an object for...", or when they're troubleshooting object deployment errors especially around sharing models and Master-Detail relationships. Always use this skill for any custom object metadata work.
+name: generating-custom-object
+description: "Use this skill when users need to create, generate, or validate Salesforce Custom Object metadata. Trigger when users mention custom objects, creating objects, object metadata, .object files, sharing models, name fields, or validation rules on objects. Also use when users say things like \"create a custom object\", \"generate object metadata\", \"set up an object for...\", or when they're troubleshooting object deployment errors especially around sharing models and Master-Detail relationships. Always use this skill for any custom object metadata work."
 ---
 
 ## When to Use This Skill

package/skills/{salesforce-custom-tab → generating-custom-tab}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: salesforce-custom-tab
-description: Use this skill when users need to create or configure Salesforce Custom Tabs. Trigger when users mention tabs, navigation tabs, object tabs, web tabs, Visualforce tabs, Lightning component tabs, app page tabs, or tab configuration. Also use when users want to add navigation to custom objects, create tabs for external content, or set up Lightning page tabs. Always use this skill for any custom tab work.
+name: generating-custom-tab
+description: "Use this skill when users need to create or configure Salesforce Custom Tabs. Trigger when users mention tabs, navigation tabs, object tabs, web tabs, Visualforce tabs, Lightning component tabs, app page tabs, or tab configuration. Also use when users want to add navigation to custom objects, create tabs for external content, or set up Lightning page tabs. Always use this skill for any custom tab work."
 ---
 
 ## When to Use This Skill

package/skills/{salesforce-experience-lwr-site → generating-experience-lwr-site}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: salesforce-experience-lwr-site
-description: Creates, modifies, or manages Salesforce Experience Cloud LWR sites via DigitalExperience metadata. Always trigger when users mention Experience sites, LWR sites, DigitalExperience, Experience Cloud, community sites, portals, creating pages, adding routes, views, theme layouts, branding sets, previewing sites, or any DigitalExperience bundle work. Also use when users mention specific content types like sfdc_cms__route, sfdc_cms__themeLayout, etc. or when troubleshooting site deployment.
+name: generating-experience-lwr-site
+description: "Creates, modifies, or manages Salesforce Experience Cloud LWR sites via DigitalExperience metadata. Always trigger when users mention Experience sites, LWR sites, DigitalExperience, Experience Cloud, community sites, portals, creating pages, adding routes, views, theme layouts, branding sets, previewing sites, or any DigitalExperience bundle work. Also use when users mention specific content types like sfdc_cms__route, sfdc_cms__themeLayout, etc. or when troubleshooting site deployment."
 ---
 
 # Experience LWR Site Builder

package/skills/{salesforce-experience-lwr-site → generating-experience-lwr-site}/docs/handle-ui-components.md

@@ -212,4 +212,4 @@ In this example the component threeColumn has 3 slots, named left, center, and r
     "definition" : "c:threeColumn",
     "id" : "b9e517c5-90ac-49e9-91b7-3730512c95a3",
     "type" : "component"
-}
+}

package/skills/generating-experience-react-site/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: generating-experience-react-site
+description: "Use this skill when users need to create or configure a Salesforce Digital Experience Site specifically for hosting a React web application. Trigger when users mention creating an Experience site for a React app, setting up a React site on Salesforce, configuring Network/CustomSite/DigitalExperience metadata for a web app, or deploying site infrastructure for a React application. Also trigger when users mention site URL path prefixes, app namespaces, appDevName, guest access configuration, DigitalExperienceConfig, DigitalExperienceBundle, or sfdc_cms__site content types in the context of React apps. Always use this skill for any React web application site creation or site infrastructure configuration work, even if the user just says \"create a site for my React app\" or \"set up the site for my web application.\""
+---
+
+# Digital Experience Site for React Web Applications
+Create and configure Digital Experience Sites that host React web applications on Salesforce. This skill generates the minimum necessary site infrastructure — Network, CustomSite, DigitalExperienceConfig, DigitalExperienceBundle, and the `sfdc_cms__site` content type — so a React app can be served from Salesforce.
+
+React sites differ from standard LWR sites: they don't need routes, views, theme layouts, or branding sets. The site acts as a thin container (`appContainer: true`) that delegates rendering to the React application referenced by `appSpace`.
+
+## Required Properties
+Resolve all five properties before generating any metadata. Each has a fallback chain — work through each option in order until a value is found.
+
+| Property | Format | How to Resolve |
+|----------|--------|----------------|
+| **siteName** | `UpperCamelCase` (e.g., `MyCommunity`) | Ask user or derive from context |
+| **siteUrlPathPrefix** | `kebab-case` (e.g., `my-community`) | User-provided, or convert siteName to kebab-case |
+| **appNamespace** | String | `namespace` in `sfdx-project.json` → `sf data query -q "SELECT NamespacePrefix FROM Organization" --target-org ${usernameOrAlias}` → default `c` |
+| **appDevName** | String | `webApplication` metadata in the project → `sf data query -q "SELECT DeveloperName FROM WebApplication" --target-org ${usernameOrAlias}` → default to siteName |
+| **enableGuestAccess** | Boolean | Ask user whether unauthenticated guest users can access site APIs → default `false` |
+
+The `appNamespace` and `appDevName` properties connect the site to the correct React application. Getting these wrong means the site deploys but shows a blank page, so take care to resolve them from real project data.
+
+## Generation Workflow
+### Step 1: Resolve All Required Properties
+Determine values for all five properties before constructing anything. Use the resolution strategies in the table above, falling through each option until a value is found.
+
+### Step 2: Create the Project Structure
+Call the `get_metadata_api_context` MCP tool to retrieve schemas for `Network`, `CustomSite`, `DigitalExperienceConfig`, and `DigitalExperienceBundle` metadata types. These schemas define the valid XML structure for each file.
+
+Create any files and directories that don't already exist, using these paths:
+
+| Metadata Type | Path |
+|--------------|------|
+| Network | `networks/{siteName}.network-meta.xml` |
+| CustomSite | `sites/{siteName}.site-meta.xml` |
+| DigitalExperienceConfig | `digitalExperienceConfigs/{siteName}1.digitalExperienceConfig-meta.xml` |
+| DigitalExperienceBundle | `digitalExperiences/site/{siteName}1/{siteName}1.digitalExperience-meta.xml` |
+| DigitalExperience (sfdc_cms__site) | `digitalExperiences/site/{siteName}1/sfdc_cms__site/{siteName}1/*` |
+
+The DigitalExperience directory contains only `_meta.json` and `content.json`. Do not create any directories other than `sfdc_cms__site` inside the bundle.
+
+### Step 3: Populate All Metadata Fields
+Use the default templates in the docs below. Values in `{braces}` are resolved property references — substitute them with the actual values from Step 1.
+
+| Metadata Type | Template Reference |
+|--------------|-------------------|
+| Network | [configure-metadata-network.md](docs/configure-metadata-network.md) |
+| CustomSite | [configure-metadata-custom-site.md](docs/configure-metadata-custom-site.md) |
+| DigitalExperienceConfig | [configure-metadata-digital-experience-config.md](docs/configure-metadata-digital-experience-config.md) |
+| DigitalExperienceBundle | [configure-metadata-digital-experience-bundle.md](docs/configure-metadata-digital-experience-bundle.md) |
+| DigitalExperience (sfdc_cms__site) | [configure-metadata-digital-experience.md](docs/configure-metadata-digital-experience.md) |
+
+### Step 4: Resolve Additional Configurations
+Address any extra configurations the user requests. Use the schemas returned by `get_metadata_api_context` in Step 2 to understand each field's purpose, and update only the minimum necessary fields.
+
+## Verification Checklist
+Before deploying, confirm:
+
+- [ ] All five required properties are resolved
+- [ ] All metadata directories and files exist per the project structure
+- [ ] All metadata fields are populated per the templates and user requests
+- [ ] `appSpace` in `content.json` matches an existing `WebApplication` metadata record
+- [ ] Deployment validates successfully:
+```bash
+sf project deploy validate --metadata Network CustomSite DigitalExperienceConfig DigitalExperienceBundle DigitalExperience --target-org ${usernameOrAlias}
+```

package/skills/generating-experience-react-site/docs/configure-metadata-custom-site.md

@@ -0,0 +1,41 @@
+# Configure Metadata: CustomSite
+
+## Purpose
+This configuration file creates a **net-new, default** CustomSite metadata record for a Digital Experience React Site. It is not intended to edit or modify an existing CustomSite record. Use this template only when provisioning a brand-new React site.
+
+## File Location
+```
+sites/{siteName}.site-meta.xml
+```
+
+## Default Template
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<CustomSite xmlns="http://soap.sforce.com/2006/04/metadata">
+    <active>true</active>
+    <allowGuestPaymentsApi>false</allowGuestPaymentsApi>
+    <allowHomePage>false</allowHomePage>
+    <allowStandardAnswersPages>false</allowStandardAnswersPages>
+    <allowStandardIdeasPages>false</allowStandardIdeasPages>
+    <allowStandardLookups>false</allowStandardLookups>
+    <allowStandardPortalPages>true</allowStandardPortalPages>
+    <allowStandardSearch>false</allowStandardSearch>
+    <authorizationRequiredPage>CommunitiesLogin</authorizationRequiredPage>
+    <bandwidthExceededPage>BandwidthExceeded</bandwidthExceededPage>
+    <browserXssProtection>true</browserXssProtection>
+    <cachePublicVisualforcePagesInProxyServers>true</cachePublicVisualforcePagesInProxyServers>
+    <clickjackProtectionLevel>SameOriginOnly</clickjackProtectionLevel>
+    <contentSniffingProtection>true</contentSniffingProtection>
+    <enableAuraRequests>true</enableAuraRequests>
+    <fileNotFoundPage>FileNotFound</fileNotFoundPage>
+    <genericErrorPage>Exception</genericErrorPage>
+    <inMaintenancePage>InMaintenance</inMaintenancePage>
+    <indexPage>CommunitiesLanding</indexPage>
+    <masterLabel>{siteName}</masterLabel>
+    <redirectToCustomDomain>false</redirectToCustomDomain>
+    <referrerPolicyOriginWhenCrossOrigin>true</referrerPolicyOriginWhenCrossOrigin>
+    <selfRegPage>CommunitiesSelfReg</selfRegPage>
+    <siteType>ChatterNetwork</siteType>
+    <urlPathPrefix>{siteUrlPathPrefix}vforcesite</urlPathPrefix>
+</CustomSite>
+```