@salesforce/afv-skills 1.4.0 → 1.5.1

package/skills/generating-flexipage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generating-flexipage
-description: "Use this skill when users need to create, generate, modify, or validate Salesforce Lightning pages (FlexiPages). Trigger when users mention RecordPage, AppPage, HomePage, Lightning pages, page layouts, adding components to pages, or page customization. Also use when users say things like \"create a Lightning page\", \"add a component to a page\", \"customize the record page\", \"generate a FlexiPage\", or when they're working with FlexiPage XML files and need help with components, regions, or deployment errors. Always use this skill for any FlexiPage-related work, even if they just mention \"page\" in the context of Salesforce."
+description: "Use this skill when users need to create, generate, modify, or validate Salesforce Lightning pages (FlexiPages). Trigger when users mention RecordPage, AppPage, HomePage, Lightning pages, page layouts, adding components to pages, or page customization. Also use when users say things like 'create a Lightning page', 'add a component to a page', 'customize the record page', 'generate a FlexiPage', or when they're working with FlexiPage XML files and need help with components, regions, or deployment errors. Always use this skill for any FlexiPage-related work, even if they just mention 'page' in the context of Salesforce."
 ---
 
 ## When to Use This Skill
@@ -20,6 +20,8 @@ Use this skill when you need to:
 
 ## Overview
 
+**CRITICAL: When creating NEW FlexiPages, you MUST ALWAYS start with the CLI template command.** Never create FlexiPage XML from scratch - the CLI provides valid structure, proper regions, and correct component configuration that prevents deployment errors.
+
 Generate Lightning pages (RecordPage, AppPage, HomePage) using CLI bootstrapping for component discovery and configuration.
 
 ---
@@ -28,6 +30,8 @@ Generate Lightning pages (RecordPage, AppPage, HomePage) using CLI bootstrapping
 
 ### Step 1: Bootstrap with CLI
 
+**MANDATORY FOR NEW PAGES: This step is NOT optional.** Always use the CLI template command when creating a new FlexiPage. The CLI generates valid XML structure, proper regions, and correct metadata that prevents common deployment errors. Only skip this step if you're editing an existing FlexiPage file.
+
 ```bash
 sf template generate flexipage \
   --name <PageName> \
@@ -39,19 +43,22 @@ sf template generate flexipage \
   --output-dir force-app/main/default/flexipages
 ```
 
-**Template-specific requirements:**
-- **RecordPage**: Requires `--sobject` (e.g., Account, Custom_Object__c)
-- **RecordPage**: Requires `--primary-field` and `--secondary-fields` for dynamic highlights, `--detail-fields` for full record details. Use the most important identifying field as primary, e.g. Name. Use the secondary fields (max 12, recommended 4-6) to show a summary of the record. Use detail fields to show the full details of the record.
-- **AppPage**: No additional requirements
-- **HomePage**: No additional requirements
-
 **Note:** If the `sf template generate flexipage` command fails, recommend users upgrade to the latest version of the Salesforce CLI:
 ```bash
 npm install -g @salesforce/cli@latest
 ```
 
+#### **Field Selection Guidelines**
+- **Validate fields exist**: Use MCP tools or describe commands to discover available fields for the object before specifying them in the command
+- **Prefer compound fields**: Use `Name` (not `FirstName`/`LastName`), `BillingAddress` (not `BillingStreet`/`BillingCity`/`BillingState`), `MailingAddress`, etc. when available
 
-**What you get:**
+#### **Template-specific requirements**
+- **RecordPage**: Requires `--sobject` (e.g., Account, Custom_Object__c)
+- **RecordPage**: Requires `--primary-field` and `--secondary-fields` for dynamic highlights, `--detail-fields` for full record details. Use the most important identifying field as primary, e.g. Name. Use the secondary fields (max 12, recommended 4-6) to show a summary of the record. Use detail fields to show the full details of the record.
+- **AppPage**: No additional requirements
+- **HomePage**: No additional requirements
+
+#### **What you get**
 - Valid FlexiPage XML with correct structure
 - Pre-configured regions and basic components
 - Proper field references and facet structure
@@ -59,17 +66,31 @@ npm install -g @salesforce/cli@latest
 
 ### Step 2: Deploy Base Page
 
+Run a **dry-run** deployment of the entire project to validate the page and dependencies:
 ```bash
-sf project deploy start --source-dir force-app/main/default/flexipages
+sf project deploy start --dry-run -d "force-app/main/default" --test-level NoTestRun --wait 10 --json
 ```
 
-**Deploy early, deploy often.** Start with the bootstrapped page, validate it works, then enhance.
+**Critical:** Fix any deployment errors before proceeding. The page must validate successfully.
+
+### Step 3: **STOP - No Further Modifications**
+
+**MANDATORY: Stop after Step 2. Do not add components or edit the FlexiPage XML.**
 
-### Step 3: Update and Redeploy
+This applies even if the user requested:
+- Additional components
+- Page customization
+- Component configuration
 
-Modify the generated XML, adding components discovered via MCP. Deploy incrementally.
+What you CAN do:
+- Suggest what components would be useful
+- Explain what enhancements are possible
+- Document what would need to be added manually
 
-**Note:** Warn users to use caution with updates beyond this step when using this command.
+What you CANNOT do:
+- Modify the XML file
+- Add any components
+- Make any enhancements
 
 ---
 
@@ -215,6 +236,10 @@ Every fieldInstance requires:
 
 ## Common Deployment Errors
 
+### "We couldn't retrieve or load the information on the field"
+**Cause:** Invalid field API name - field doesn't exist on the object or has incorrect spelling
+**Fix:** Use MCP tools or describe commands to discover valid fields, then update the field reference (see Field Selection Guidelines)
+
 ### "Invalid field reference"
 **Cause:** Used `ObjectName.Field` instead of `Record.Field`  
 **Fix:** Change to `Record.{FieldApiName}`
@@ -245,49 +270,6 @@ Every fieldInstance requires:
 
 ---
 
-## Incremental Development Pattern
-
-**Philosophy:** Deploy small, working increments. Don't build entire complex page at once.
-
-**Process:**
-1. **CLI bootstrap** → Deploy base page
-2. **Add one component** → Deploy
-3. **Add another component** → Deploy
-4. **Repeat** until complete
-
-**Benefits:**
-- Isolated errors (know exactly what broke)
-- Faster debugging
-- Build confidence with each success
-- Get user feedback early
-
-**Anti-pattern:** Building entire complex page → one giant error cascade.
-
----
-
-## Adding Components to Existing FlexiPages
-
-### Workflow
-
-When user provides an existing FlexiPage file path:
-
-1. **Read the file** using native file I/O
-2. **Parse XML** to extract:
-   - **ALL existing component identifiers** (search for all `<identifier>` tags)
-   - **ALL existing region/facet names** (search for all `<name>` tags in `<flexiPageRegions>`)
-   - Available regions (parse from file, don't assume names)
-   - Existing facets
-3. **Verify uniqueness** - ensure your new identifiers and names don't conflict with ANY existing ones
-4. **Check if target facet exists** - if adding to a named facet like `detailTabContent` that already exists:
-   - **Add new `<itemInstances>` to existing region** (don't create duplicate region)
-   - **Insert before the closing `</flexiPageRegions>` tag of that region**
-5. **Generate component XML** (apply all rules from "Critical XML Rules" section)
-6. **Insert** into appropriate region or add itemInstances to existing facet
-7. **Write** modified XML back to file
-8. **Deploy**: `sf project deploy start --source-dir force-app/...`
-
----
-
 ### Generating Unique Identifiers
 
 **CRITICAL: Before generating ANY new identifier or facet name, follow the rules in section 5 of "Critical XML Rules" above.**
@@ -474,7 +456,7 @@ Identifier Pattern: flexipage_richText or flexipage_richText_{sequence}
 ## Validation Checklist
 
 Before deploying:
-- [ ] Used CLI to bootstrap (don't start from scratch)
+- [ ] **[NEW PAGES ONLY]** Used CLI to bootstrap - NEVER create FlexiPage XML from scratch
 - [ ] **ALL identifiers are unique** - no duplicate `<identifier>` values anywhere in file
 - [ ] **ALL region/facet names are unique** - no duplicate `<name>` values in `<flexiPageRegions>`
 - [ ] **Multiple components in same facet are combined** - ONE region with multiple `<itemInstances>`, NOT separate regions with same name

package/skills/searching-media/SKILL.md

@@ -0,0 +1,342 @@
+---
+name: searching-media
+description: "Searches for and retrieves existing visual media (images, logos, icons, photos, graphics, banners, thumbnails, hero images, backgrounds) from any source. Use this skill ANY TIME a user request involves finding, searching, getting, fetching, retrieving, grabbing, looking up, or locating media. Takes PRIORITY and activates FIRST when ANY media search/retrieval is mentioned, regardless of what else happens with the media afterward. Triggers for requests like \"search for logo\", \"find hero image\", \"get company logo\", \"locate icons\", \"fetch background image\", \"retrieve product photos\". Handles the search and source selection workflow. Does not apply when the request is to generate NEW images with AI, design custom graphics from scratch, or edit existing images."
+compatibility: "Requires search_media_cms_channels and/or search_electronic_media MCP tools"
+metadata:
+  version: "1.0"
+---
+
+# Media Search
+
+Universal routing skill for searching and retrieving existing images and media.
+
+## Scope
+
+**This skill is for SEARCHING FOR existing media, not CREATING new media.**
+
+**Use this skill when the user wants to:**
+- Search for images in Salesforce CMS, Data Cloud
+- Find existing visual assets to use in their app
+- Retrieve media from connected sources
+- Browse available images for their project
+- Locate specific photos or graphics
+
+**DO NOT use this skill when the user wants to:**
+- Generate new images with AI (use image generation tools)
+- Create graphics or designs from scratch
+- Edit or modify existing images
+- Build custom visuals or diagrams
+
+## Before You Search
+
+**CRITICAL: This is a routing skill, not a direct search skill.**
+
+When a user requests to find an image:
+
+**Your first response MUST be plain text only — zero tool calls.** You MUST follow this sequence:
+
+1. **First response MUST be text only:** A numbered list of search sources for the user. No tool calls of any kind.
+2. **Wait for user to reply** with their selected option number
+3. **Only then** call the appropriate search tool (this is the FIRST tool call in the entire interaction)
+
+**Example of what NOT to do:**
+- ❌ Calling ANY tool before the user picks a source (MCP tools, file reads, descriptor checks, etc.)
+- ❌ "Checking which MCP tools are available" — do not probe or discover tools via tool calls
+- ❌ Immediately calling `search_electronic_media` or `search_media_cms_channels`
+- ❌ Reading MCP tool descriptors or schemas to see what's available
+- ❌ Deciding which search source to use without asking
+
+**Example of what TO do:**
+- ✅ Respond with ONLY text — a numbered list of search sources
+- ✅ Ask: "Which option would you like to use?"
+- ✅ Wait for user to reply with their choice
+- ✅ Then (and only then) call the tool they selected
+
+**Your first response when this skill triggers MUST be a text-only message presenting search sources. No tool calls. No exceptions.**
+
+
+## Workflow Overview
+
+**The user MUST choose the search source. You CANNOT skip this step.**
+
+Copy this checklist and track your progress:
+
+```
+Media Search Progress:
+- [ ] Step 1: Check your own tool list for available search tools (no tool calls — just inspect what's in your context)
+- [ ] Step 2: Present only the available options to the user as a numbered list (plain text, no tool calls)
+- [ ] Step 3: Wait for the user to reply with their selection
+- [ ] Step 4: Execute the selected search method (this is the first tool call)
+- [ ] Step 5: Present all results to user for selection
+- [ ] Step 6: Apply selected image to code
+```
+
+If you call any tool before step 4, you are not following this skill correctly.
+
+## Presenting Search Sources (First Response)
+
+**DO NOT call any tool, read any MCP descriptor, or make any external request to determine available tools.**
+
+Your tools are already loaded into your context. Look at the tool names you already have access to — this is introspection, not a tool call.
+
+**Step 1: Check your own tool list (no tool calls)**
+
+Look at the tools already in your context and check for these names:
+- `search_media_cms_channels` → If present, include **"Search using keywords"**
+- `search_electronic_media` → If present, include **"Search using Data 360 hybrid search"**
+- Always include **"Other"** as the last option
+
+**Step 2: Build your response**
+
+Include ONLY the sources whose tools you actually have. Number them sequentially.
+
+```
+I can help you find that image. Where would you like to search?
+
+[NUMBER]. [SEARCH SOURCE NAME] — [Brief description]
+...
+[NUMBER]. Other — Provide your own URL or path
+
+Which option would you like to use?
+```
+
+**Step 3: Stop and wait**
+
+After presenting the list, STOP. Do not call any tool. Do not proceed. Wait for the user to reply with their choice.
+
+### Examples
+
+**Both tools available:**
+```
+I can help you find that image. Where would you like to search?
+
+1. Search using Data 360 hybrid search — Semantic search across Salesforce CMS and connected DAMs
+2. Search using keywords — Search Salesforce CMS by keywords and taxonomies
+3. Other — Provide your own URL or path
+
+Which option would you like to use?
+```
+
+**Only `search_media_cms_channels` available:**
+```
+I can help you find that image. Where would you like to search?
+
+1. Search using keywords — Search Salesforce CMS by keywords and taxonomies
+2. Other — Provide your own URL or path
+
+Which option would you like to use?
+```
+
+**Only `search_electronic_media` available:**
+```
+I can help you find that image. Where would you like to search?
+
+1. Search using Data 360 hybrid search — Semantic search across Salesforce CMS and connected DAMs
+2. Other — Provide your own URL or path
+
+Which option would you like to use?
+```
+
+**Neither tool available:**
+```
+No automated media search sources are currently configured. Please provide a direct URL or asset library path.
+```
+
+**Wait for the user to select** before proceeding.
+
+## Executing the Selected Search Method
+
+**⚠️ ONLY reach this step if the user has explicitly selected an option from your numbered list.**
+
+If you haven't shown options yet, go back to the "Presenting Search Sources" section first.
+
+After the user selects an option, execute the corresponding search method below.
+
+### Search using keywords
+
+**Tool:** `search_media_cms_channels`
+
+**Process:**
+
+1. **Analyze the query** — Understand what the user is searching for (subject, attributes, domain)
+
+2. **Extract keywords** — Concrete nouns that would appear in image metadata
+   - Use domain-specific synonyms
+   - Maximum 10 terms
+   - Examples:
+     - "luxury apartments" → apartment, villa, penthouse, residence, condo
+     - "company logo" → logo, emblem, corporate logo
+     - "bright room" → _(empty if no concrete nouns)_
+
+3. **Extract taxonomies** — Descriptive qualities, styles, moods, categories
+   - Only adjectives and attributes
+   - Examples:
+     - "luxury apartment with river view" → Luxury, Premium, Waterfront, Riverside, Panoramic
+     - "bright spacious room" → Bright, Spacious, Open, Airy, Light
+     - "car" → _(empty if no descriptive terms)_
+
+4. **Determine locale** — Use format `en_US`, `es_MX`, `fr_FR` (default: `en_US`)
+
+5. **Build the JSON payload** — Construct this exact structure:
+
+```json
+{
+  "inputs": [{
+    "searchKeyword": "keyword1 OR keyword2 OR keyword3",
+    "taxonomyExpression": "{\"OR\": [\"Taxonomy1\", \"Taxonomy2\"]}",
+    "searchLanguage": "en_US",
+    "channelIds": "",
+    "channelType": "PublicUnauthenticated",
+    "contentTypeFqn": "sfdc_cms__image",
+    "pageOffset": 0,
+    "searchLimit": 5
+  }]
+}
+```
+
+**Field rules:**
+- `searchKeyword`: Join keywords with ` OR ` (space-OR-space). Use empty string if no keywords.
+- `taxonomyExpression`: Stringify JSON object `{"OR": ["term1", "term2"]}`. Use `"{}"` if no taxonomies.
+- `searchLanguage`: Locale with underscore (e.g., `en_US`)
+- `channelIds`: Always empty string
+- `channelType`: Always `"PublicUnauthenticated"`
+- `contentTypeFqn`: Always `"sfdc_cms__image"`
+- `pageOffset`: Start at `0`, increment by `searchLimit` for pagination
+- `searchLimit`: Default `5`, adjust if user requests more
+
+**Examples:**
+
+Query: "luxury apartment with river view"
+```json
+{
+  "inputs": [{
+    "searchKeyword": "apartment OR villa OR penthouse OR residence",
+    "taxonomyExpression": "{\"OR\": [\"Luxury\", \"Premium\", \"Waterfront\", \"Riverside\"]}",
+    "searchLanguage": "en_US",
+    "channelIds": "",
+    "channelType": "PublicUnauthenticated",
+    "contentTypeFqn": "sfdc_cms__image",
+    "pageOffset": 0,
+    "searchLimit": 5
+  }]
+}
+```
+
+Query: "bright spacious room" (no concrete nouns)
+```json
+{
+  "inputs": [{
+    "searchKeyword": "",
+    "taxonomyExpression": "{\"OR\": [\"Bright\", \"Spacious\", \"Open\", \"Airy\"]}",
+    "searchLanguage": "en_US",
+    "channelIds": "",
+    "channelType": "PublicUnauthenticated",
+    "contentTypeFqn": "sfdc_cms__image",
+    "pageOffset": 0,
+    "searchLimit": 5
+  }]
+}
+```
+
+Query: "car images" (no descriptive terms)
+```json
+{
+  "inputs": [{
+    "searchKeyword": "car OR automobile OR vehicle OR auto",
+    "taxonomyExpression": "{}",
+    "searchLanguage": "en_US",
+    "channelIds": "",
+    "channelType": "PublicUnauthenticated",
+    "contentTypeFqn": "sfdc_cms__image",
+    "pageOffset": 0,
+    "searchLimit": 5
+  }]
+}
+```
+
+6. **Call the tool** with the exact JSON payload
+
+### Search using Data 360 hybrid search
+
+**Tool:** `search_electronic_media`
+
+**Process:**
+
+1. Use the user's query **as-is** — no keyword extraction or transformation needed
+2. Call `search_electronic_media`
+3. Pass the query to the tool's `searchQuery` parameter
+
+**Example:**
+- User query: "modern luxury apartment with natural lighting"
+- Tool call: `search_electronic_media(searchQuery="modern luxury apartment with natural lighting")`
+
+### Other (User-Provided URL)
+
+Ask the user to provide:
+- Direct URL to the image
+- Asset library path
+- Specific system/location to check
+
+## Presenting Search Results
+
+Parse the tool response and present **ALL** results as numbered options. Show the image title only — do not display the URL. When the user selects an option, use the URL internally to apply the image.
+
+```
+I found 4 images. Which one would you like to use?
+
+1. Luxury Apartment Exterior
+   Source: Salesforce CMS
+
+2. Modern High-Rise Building
+   Source: Salesforce CMS
+
+3. Waterfront Residence
+   Source: Salesforce CMS
+
+4. Premium Condominium
+   Source: Salesforce CMS
+```
+
+**Never auto-select an image.** Always wait for user choice.
+
+## Applying the Selected Image
+
+After the user chooses:
+
+1. Confirm the selection with image name and URL
+2. Use the complete URL returned by the tool, including all query parameters. CMS and DAM URLs rely on query parameters for authentication, resizing, and CDN routing — dropping them breaks the image. For example, a URL like `https://cms.example.com/media/img.jpg?oid=00D&refid=0EM&v=2` must be used in full.
+3. Apply the URL to the user's code/component
+4. Show what was changed (file path and line number)
+
+## Error Handling
+
+| Error | Response |
+|---|---|
+| Tool unavailable | "The [source name] tool is unavailable. Would you like to try a different source?" |
+| Tool returns error | Show error message, offer retry with different terms or alternative source |
+| No results found | "No results found. Try broader keywords, removing descriptive terms, or a different source." |
+| Invalid user selection | Re-display options and ask again |
+
+**Never silently fail.** Always inform the user and offer alternatives.
+
+## Search Behavior Notes
+
+**Search using keywords:**
+- Both keyword and taxonomy → results match keyword OR (keyword + taxonomy)
+- Empty keyword → search by taxonomy only
+- Empty taxonomy → search by keyword only
+- Use `pageOffset` for pagination (increment by `searchLimit`)
+
+**Search using Data 360 hybrid search:**
+- Handles natural language queries
+- Semantic similarity matching
+- Searches across multiple connected systems
+
+## Key Principles
+
+1. **First response is always text-only** — Present search sources without calling any tool
+2. **Only show configured sources** — Check your own tool list (introspection, not tool calls) and only present sources whose tools you have
+3. **Wait for user selection** — Never auto-select a source or image
+4. **Show all results** — Let the user choose the best match
+5. **Confirm before applying** — Verify the selection before modifying code
+6. **Handle errors gracefully** — Provide clear feedback and alternatives