@salesforce/afv-skills 1.1.0 → 1.3.0

package/skills/fetching-webapp-rest-api/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: fetching-webapp-rest-api
+description: REST API usage via the Data SDK fetch method. Use when implementing Chatter, Connect REST, Apex REST, UI API REST, or Einstein LLM calls — only when GraphQL is not sufficient.
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.graphql"
+---
+
+# Salesforce REST API via Data SDK Fetch
+
+Use `sdk.fetch` from the Data SDK when GraphQL is not sufficient. The SDK applies authentication, CSRF handling, and base URL resolution. **Always use optional chaining** (`sdk.fetch?.()`) and handle the case where `fetch` is not available.
+
+Invoke this skill when you need to call Chatter, Connect REST, Apex REST, UI API REST, or Einstein LLM endpoints.
+
+## API Version
+
+Use the project's API version. It is typically injected as `__SF_API_VERSION__`; fallback to `"65.0"`:
+
+```typescript
+declare const __SF_API_VERSION__: string;
+const API_VERSION = typeof __SF_API_VERSION__ !== "undefined" ? __SF_API_VERSION__ : "65.0";
+```
+
+## Base Path
+
+URLs are relative to the Salesforce API base. The SDK prepends the correct base path. Use paths starting with `/services/...`.
+
+---
+
+## Chatter API
+
+User and collaboration data. No GraphQL equivalent.
+
+| Endpoint | Method | Purpose |
+| -------- | ------ | ------- |
+| `/services/data/v{version}/chatter/users/me` | GET | Current user (id, name, email, username) |
+
+```typescript
+const sdk = await createDataSDK();
+const response = await sdk.fetch?.(`/services/data/v${API_VERSION}/chatter/users/me`);
+
+if (!response?.ok) throw new Error(`HTTP ${response?.status}`);
+const data = await response.json();
+return { id: data.id, name: data.name };
+```
+
+---
+
+## Connect REST API
+
+File and content operations.
+
+| Endpoint | Method | Purpose |
+| -------- | ------ | ------- |
+| `/services/data/v{version}/connect/file/upload/config` | GET | Upload config (token, uploadUrl) for file uploads |
+
+```typescript
+const sdk = await createDataSDK();
+const configRes = await sdk.fetch?.(`/services/data/v${API_VERSION}/connect/file/upload/config`, {
+  method: "GET",
+});
+
+if (!configRes?.ok) throw new Error(`Failed to get upload config: ${configRes?.status}`);
+const config = await configRes.json();
+const { token, uploadUrl } = config;
+```
+
+---
+
+## Apex REST
+
+Custom Apex REST resources. Requires corresponding Apex classes in the org. CSRF protection is applied automatically for `services/apexrest` URLs.
+
+| Endpoint | Method | Purpose |
+| -------- | ------ | ------- |
+| `/services/apexrest/auth/login` | POST | User login |
+| `/services/apexrest/auth/register` | POST | User registration |
+| `/services/apexrest/auth/forgot-password` | POST | Request password reset |
+| `/services/apexrest/auth/reset-password` | POST | Reset password with token |
+| `/services/apexrest/auth/change-password` | POST | Change password (authenticated) |
+| `/services/apexrest/{resource}` | GET/POST | Custom Apex REST resources |
+
+**Example (login):**
+
+```typescript
+const sdk = await createDataSDK();
+const response = await sdk.fetch?.("/services/apexrest/auth/login", {
+  method: "POST",
+  body: JSON.stringify({ email, password, startUrl: "/" }),
+  headers: { "Content-Type": "application/json", Accept: "application/json" },
+});
+```
+
+Apex REST paths do not include the API version.
+
+---
+
+## UI API (REST)
+
+When GraphQL cannot cover the use case. **Prefer GraphQL** when possible.
+
+| Endpoint | Method | Purpose |
+| -------- | ------ | ------- |
+| `/services/data/v{version}/ui-api/records/{recordId}` | GET | Fetch a single record |
+
+```typescript
+const sdk = await createDataSDK();
+const response = await sdk.fetch?.(`/services/data/v${API_VERSION}/ui-api/records/${recordId}`);
+```
+
+---
+
+## Einstein LLM Gateway
+
+AI features. Requires Einstein API setup.
+
+| Endpoint | Method | Purpose |
+| -------- | ------ | ------- |
+| `/services/data/v{version}/einstein/llm/prompt/generations` | POST | Generate text from Einstein LLM |
+
+```typescript
+const sdk = await createDataSDK();
+const response = await sdk.fetch?.(`/services/data/v${API_VERSION}/einstein/llm/prompt/generations`, {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({
+    additionalConfig: { applicationName: "PromptTemplateGenerationsInvocable" },
+    promptTextorId: prompt,
+  }),
+});
+
+if (!response?.ok) throw new Error(`Einstein LLM failed (${response?.status})`);
+const data = await response.json();
+return data?.generations?.[0]?.text ?? "";
+```
+
+---
+
+## General Pattern
+
+```typescript
+import { createDataSDK } from "@salesforce/sdk-data";
+
+const sdk = await createDataSDK();
+
+if (!sdk.fetch) {
+  throw new Error("Data SDK fetch is not available in this context");
+}
+
+const response = await sdk.fetch(url, {
+  method: "GET", // or POST, PUT, PATCH, DELETE
+  headers: { "Content-Type": "application/json", Accept: "application/json" },
+  body: method !== "GET" ? JSON.stringify(payload) : undefined,
+});
+
+if (!response.ok) throw new Error(`HTTP ${response.status}`);
+const data = await response.json();
+```
+
+---
+
+## Reference
+
+- Parent: `accessing-data` — enforces Data SDK usage for all Salesforce data fetches
+- GraphQL: `using-graphql` — use for record queries and mutations when possible
+- `createRecord` from `@salesforce/webapp-experimental/api` for UI API record creation (uses SDK internally)

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

@@ -1,5 +1,5 @@
 ---
-name: salesforce-custom-application
+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.
 ---
 
@@ -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
@@ -43,7 +42,7 @@ Custom applications (Lightning Apps) that group tabs and functionality to provid
 - **description**: Brief description of the application's purpose
 - **tabs**: Array of tab names to include
 - **utilityBar**: API name of the Utility Bar configuration
-- **brand**: ⚠️ HIGHLY RECOMMENDED - Branding configuration object (headerColor, shouldOverrideOrgTheme, footerColor, primaryTabColor)
+- **brand**: ⚠️ HIGHLY RECOMMENDED - Branding configuration object (headerColor, shouldOverrideOrgTheme, footerColor)
 - **actionOverrides**: ⚠️ REQUIRED when custom record pages exist - Action override configuration (actionName, content, formFactor, type, pageOrSobjectType)
 - **profileActionOverrides**: Profile-specific action overrides (actionName, content, formFactor, pageOrSobjectType, type, profile)
 - **isNavAutoTempTabsDisabled**: Navigation behavior setting (default: false)
@@ -86,7 +85,6 @@ Custom applications (Lightning Apps) that group tabs and functionality to provid
 - **brand.headerColor**: Header bar color in hex format (e.g., "#0070D2") - RECOMMENDED
 - **brand.shouldOverrideOrgTheme**: Override organization theme (true/false) - Default: false
 - **brand.footerColor**: Footer color in hex format
-- **brand.primaryTabColor**: Primary tab color in hex format
 
 ### Action Overrides (CRITICAL - DO NOT SKIP)
 **IMPORTANT**: Action overrides MUST be created for every custom object tab that has a record page generated by flexipage expert.

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

@@ -1,5 +1,5 @@
 ---
-name: salesforce-custom-field
+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.
 ---
 
@@ -42,10 +42,6 @@ Every generated field must include these tags:
 | `<description>` | Mandatory | State the business "why" behind the field |
 | `<inlineHelpText>` | Mandatory | Provide actionable guidance for the end-user. Must add value beyond the label (e.g., "Enter the value in USD including tax" instead of just "The amount") |
 
-### XML Comments — NEVER Before Root Element
-
-**NEVER place XML comments (`<!-- ... -->`) before the root `<CustomField>` element in metadata XML files.** Comments between the XML declaration and `<CustomField>` cause a `ConversionError` during deployment. Comments inside the root element are safe.
-
 ### External ID Configuration
 
 **Trigger:** If the user mentions "integration," "importing data," "external system ID," or "unique key from [System Name]," set `<externalId>true</externalId>`.

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

@@ -1,5 +1,5 @@
 ---
-name: salesforce-custom-lightning-type
+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.
 ---
 
@@ -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,5 +1,5 @@
 ---
-name: salesforce-custom-object
+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.
 ---
 

package/skills/generating-custom-tab/SKILL.md

@@ -0,0 +1,154 @@
+---
+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
+
+Use this skill when you need to:
+- Create tabs for objects, web pages, or Visualforce pages
+- Add navigation tabs to applications
+- Configure tab visibility and access
+- Troubleshoot deployment errors related to custom tabs
+
+## Specification
+
+# CustomTab Metadata Specification
+
+## 📋 Overview
+Custom tabs for navigating to objects, web content, or Visualforce pages within Salesforce applications.
+
+## 🎯 Purpose
+- Provide navigation to custom objects
+- Link to external web content
+- Access Visualforce pages
+- Organize application navigation
+
+## ⚙️ Required Properties
+
+### Core Tab Properties
+- **customObject**: `true` for custom object tabs, `false` for all others.
+- **motif**: Tab icon style — choose a motif that semantically matches the object's purpose. Do NOT reuse the same motif for every tab.
+- **label**: Display name (required for non-object tabs ONLY; object tabs inherit label from the object)
+- **url**: Web URL (for web tabs)
+- **page**: Visualforce page name (for Visualforce tabs)
+
+
+### 🚨 STRICT ELEMENT ALLOWLIST — READ THIS FIRST
+
+**The root element MUST always be `<CustomTab>` (NOT `<Tab>`).** The XML namespace must be `xmlns="http://soap.sforce.com/2006/04/metadata"`.
+
+Only the elements listed below are valid. **Any element not on this list WILL cause a deployment error.**
+
+| Tab Type | ONLY these elements are allowed (nothing else) |
+|---|---|
+| **Object tabs** | `<customObject>` (required, set to `true`), `<motif>` (required), `<description>` (optional) |
+| **Web tabs** | `<customObject>` (required, set to `false`), `<label>` (required), `<motif>` (required), `<url>` (required), `<urlEncodingKey>` (required, set to `UTF-8`), `<description>` (optional), `<frameHeight>` (optional) |
+| **Visualforce tabs** | `<customObject>` (required, set to `false`), `<label>` (required), `<motif>` (required), `<page>` (required), `<description>` (optional) |
+
+### ⚠️ FORBIDDEN ELEMENTS (every one of these causes a deployment error)
+`<sobjectName>`, `<name>`, `<fullName>`, `<apiVersion>`, `<isHidden>`, `<tabVisibility>`, `<type>`, `<mobileReady>`, `<urlFrameHeight>`, `<urlType>`, `<urlRedirect>`, `<encodingKey>`, `<height>`, `<auraComponent>`
+
+Also forbidden:
+- `<label>` on object tabs (object tabs inherit their label from the custom object)
+- `<page>` on web tabs (only for Visualforce tabs)
+- Empty elements like `<page></page>` or `<description></description>`
+- Any element not in the allowlist table above
+
+## 🔧 Tab Types
+
+### Object Tabs
+- **Purpose**: Navigate to custom or standard objects
+- **File name** determines the object: `{ObjectApiName}.tab-meta.xml` (e.g., `Space_Station__c.tab-meta.xml`)
+- **Required elements**: `<customObject>true</customObject>` and `<motif>`
+- **Correct example** (for a Space_Station__c.tab-meta.xml):
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<CustomTab xmlns="http://soap.sforce.com/2006/04/metadata">
+    <customObject>true</customObject>
+    <motif>Custom39: Telescope</motif>
+</CustomTab>
+```
+- **Correct example** (for a Supply__c.tab-meta.xml — note different motif):
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<CustomTab xmlns="http://soap.sforce.com/2006/04/metadata">
+    <customObject>true</customObject>
+    <motif>Custom98: Truck</motif>
+</CustomTab>
+```
+- **❌ WRONG** — do NOT add `<sobjectName>`, `<name>`, `<fullName>`, or `<label>`:
+```xml
+<CustomTab xmlns="http://soap.sforce.com/2006/04/metadata">
+    <sobjectName>Space_Station__c</sobjectName>  <!-- DEPLOYMENT ERROR -->
+    <label>Space Station</label>                  <!-- DEPLOYMENT ERROR on object tabs -->
+    <customObject>true</customObject>
+    <motif>Custom57: Desert</motif>
+</CustomTab>
+```
+
+### Web Tabs
+- **Purpose**: Link to external websites or web applications
+- **File name**: Use a descriptive name: `{TabName}.tab-meta.xml` (e.g., `Knowledge_Base.tab-meta.xml`)
+- **COPY THIS EXACT TEMPLATE** — only replace the placeholder values. Do NOT add, remove, or rename any XML elements:
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<CustomTab xmlns="http://soap.sforce.com/2006/04/metadata">
+    <customObject>false</customObject>
+    <description>REPLACE_WITH_DESCRIPTION</description>
+    <frameHeight>600</frameHeight>
+    <label>REPLACE_WITH_LABEL</label>
+    <motif>REPLACE_WITH_MOTIF</motif>
+    <url>REPLACE_WITH_URL</url>
+    <urlEncodingKey>UTF-8</urlEncodingKey>
+</CustomTab>
+```
+- **These 7 elements above are the ONLY elements allowed in a web tab file.** Do not add ANY other elements.
+- The `<description>` element is optional — you may remove it if not needed, but do not add anything else.
+
+### Visualforce Tabs
+- **Purpose**: Access custom Visualforce pages
+- **File name**: `{TabName}.tab-meta.xml` (e.g., `Custom_Page_Tab.tab-meta.xml`)
+- **Required elements**: `<customObject>false</customObject>`, `<label>`, `<motif>`, `<page>`
+- **Correct example**:
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<CustomTab xmlns="http://soap.sforce.com/2006/04/metadata">
+    <customObject>false</customObject>
+    <label>Custom Page</label>
+    <motif>Custom46: Computer</motif>
+    <page>CustomPage</page>
+</CustomTab>
+```
+
+## 🎨 Tab Configuration
+
+### Tab Style
+- **Default**: Use standard tab styling
+- **Custom**: Can specify custom tab styles if needed
+
+### Tab Visibility
+- **Default**: Visible to all users with access
+- **Custom**: Can be configured for specific user profiles
+
+## 📱 Supported Applications
+- **Standard Apps**: Available in standard Salesforce applications
+- **Custom Apps**: Can be included in custom applications
+- **Community Apps**: Available in community applications
+
+## 🔗 Integration Points
+- **Object Relationships**: Links to related object records
+- **Web Content**: External website integration
+- **Visualforce Pages**: Custom page functionality
+- **Lightning Components**: Modern component integration
+## ✅ Best Practices
+- Use clear, descriptive tab labels
+- Choose appropriate tab types for functionality
+- **Select a unique, contextually relevant motif for each tab** — do not default every tab to the same icon
+- Consider user experience and navigation flow
+- Test tab functionality across different applications
+- Ensure proper permissions and visibility settings
+- Follow consistent naming conventions
+- Object tab files MUST only contain `<customObject>true</customObject>` and `<motif>` — nothing else
+- Web tab files MUST only contain: `<customObject>false</customObject>`, `<label>`, `<motif>`, `<url>`, `<urlEncodingKey>`, and optionally `<description>`, `<frameHeight>` — nothing else
+- Never include `<isHidden>`, `<tabVisibility>`, `<type>`, `<mobileReady>`, or empty elements