@salesforce/afv-skills 1.37.0 → 1.38.0

package/skills/experience-aura-lwc-migrate/references/aura-slots-expert.md

@@ -0,0 +1,67 @@
+## 🎰 Slots Expert Analysis Framework
+
+### Analysis Focus
+
+Analyze component composition patterns, content projection, and child component integration in the Aura component.
+
+### Key Areas to Review
+
+#### 1. Aura Facet Analysis
+
+- Look for `<aura:facet>` declarations and usage
+- Document how facets are used for content projection
+- Identify dynamic facet content and conditional rendering
+- Note any nested facet patterns or complex compositions
+
+#### 2. Body Content Patterns
+
+- Analyze `{!v.body}` usage for content projection
+- Document how child components are composed
+- Identify conditional rendering of body content
+- Note any iteration patterns over child elements
+
+#### 3. Component Composition
+
+- Find all child components and their content patterns
+- Document how content is passed to child components
+- Identify any wrapper or container component patterns
+- Note any dynamic component creation or destruction
+
+#### 4. Content Distribution
+
+- Analyze how different content types are distributed
+- Document named slots vs default content patterns
+- Identify any content transformation or filtering
+- Note accessibility considerations for content structure
+
+### Migration Considerations
+
+#### Default Slot Analysis
+
+Your task is to identify a placeholder for an anonymous block of markup that translates into a default slot in LWC.
+Named slots or other elements and attributes are not part of this analysis and will be covered separately.
+In Aura an anonymous block of markup is injected using the expression "{!v.body}" or "{#v.body}".
+
+Review Aura component above and fix its blueprint using following rules:
+
+1. Every occurance of the expression "{!v.body}" or "{#v.body}" should be present as an element in the "contentRequirements" section.
+2. If such element has already been added, do not add another one but update one that has been added by adding "default slot" in "what" section.
+3. LWC components can have only one default slot, so it's crucial to include conditions under which this fragment is present in "what".
+
+- For each issue found, provide a separate, detailed report.
+- Keep issues concise, avoid duplicated issues or unnecessary or non-applicable problems.
+
+#### Named Slot Analysis
+
+In Aura, placeholders for blocks of markup are added by declaring attributes with type "Aura.Component" or "Aura.Component[]" for one or more component instances.
+Such placeholders are similar to slots in LWC web components.
+
+Review Aura component above and fix its blueprint using following rules:
+
+1. Every `<aura:attribute>` with type "Aura.Component" or "Aura.Component[]" should be added as an element in the "contentRequirements" section.
+2. Only elements for `<aura:attribute>` with type "Aura.Component" or "Aura.Component[]" can be added as part of this review. Ignore all other elements.
+3. The "name" of the included element should be set to the name of the attribute.
+4. The "what" of the included element should be set to "named slot inside <name of other existing item inside contentRequirements or root>".
+
+- For each issue found, provide a separate, detailed report.
+- Keep issues concise, avoid duplicated issues or unnecessary or non-applicable problems.

package/skills/experience-aura-lwc-migrate/references/aura-style-expert.md

@@ -0,0 +1,62 @@
+## 🎨 Style Expert Analysis Framework
+
+### Analysis Focus
+
+Analyze styling patterns, CSS architecture, and design token usage in the Aura component.
+
+### Key Areas to Review
+
+#### 1. CSS File Analysis
+
+- Document all CSS classes and their purposes
+- Identify SLDS (Salesforce Lightning Design System) usage patterns
+- Note any custom CSS that may conflict with LWC styling
+- Check for responsive design patterns and media queries
+
+#### 2. Styling Token Usage
+
+- Look for design token references and their usage
+- Document theme customization patterns
+- Identify brand-specific styling requirements
+- Note any dynamic styling based on component state
+
+#### 3. CSS Encapsulation Patterns
+
+- Analyze CSS scoping and inheritance patterns
+- Document any global CSS dependencies
+- Identify component-specific styling isolation
+- Note potential CSS conflicts or specificity issues
+
+#### 4. Dynamic Styling
+
+- Find any JavaScript-based style manipulation
+- Document conditional styling based on component state
+- Identify user preference or theme switching patterns
+- Note any performance-critical styling operations
+
+### Migration Considerations
+
+- Aura CSS files become LWC CSS modules with different scoping
+- SLDS usage patterns may need updates for LWC compatibility
+- CSS custom properties and design tokens have different APIs
+- Shadow DOM styling requires different approaches
+- Global CSS access is more restricted in LWC
+
+### Additional knowledge
+
+#### Style Intent analysis
+
+Your task is to look at the Aura Component definition, and make sure that the blueprint only describes the experiences a user may have with a component.
+Developers often accidentially expose APIs that allow customization of styles or CSS classes.
+
+Review Aura component above and fix its blueprint using following rules:
+
+1. Look for the following patterns: an attribute name that suggests it may be used for passing styles or CSS class names.
+2. For each match found, reason about the intent around the reference. Why is the style being provided and what is it used for in the component?
+3. Review existing sections in the blueprint, and propose updates if necessary.
+
+- If something appears in the 'styling' section already, verify it doesn't appear the data section.
+- If something appears in both sections, the dataRequirements section should be updated to remove it.
+
+* For each issue found, provide a separate, detailed report.
+* Keep issues concise, avoid duplicated issues or unnecessary or non-applicable problems.

package/skills/experience-aura-lwc-migrate/references/aura-to-lwc-completeness-checklist.md

@@ -0,0 +1,188 @@
+# Aura to LWC Conversion Completeness Checklist
+
+You are a Salesforce principal architect. Your task is to help a developer verify whether their conversion of a Salesforce Aura component to a Lightning Web Component (LWC) is truly complete. This is a developer-focused self-checklist, not a platform evaluation or LLM-as-judge scenario. The goal is to provide confidence and clarity for the developer, not to benchmark platform performance.
+
+## Instructions
+
+1. **Review the Completeness Metrics:**
+   For each of the following metrics, use the provided rating to assess the LWC conversion. For each metric, select one of the following qualitative ratings:
+
+   - **Excellent**: Perfect or near-perfect match in understanding and detail
+   - **Good**: Strong understanding with minor differences
+   - **Satisfactory**: Adequate understanding with some notable differences
+   - **Limited**: Basic understanding with significant gaps
+   - **Poor**: Major misunderstandings or omissions
+   - **Missing**: Issue completely overlooked or fatally misunderstood
+
+2. **For Each Metric:**
+
+   - State the metric and its description
+   - Assign a rating (from the list above)
+   - Provide a brief justification for the rating
+   - Optionally, add one or two sentences explaining any gaps, strengths, or issues
+
+3. **Checklist Output:**
+
+   - Present your results as a list, not a table
+   - For each metric, include:
+     - Metric name
+     - Description
+     - Rating
+     - Justification/comments
+
+4. **Summary and Recommendations:**
+
+   - At the end, summarize your overall confidence in the conversion's completeness
+   - List specific, actionable recommendations to address any gaps or issues
+
+5. **Context:**
+
+   - The component name is: `{{componentName}}`
+   - The Aura component file is: `{{componentName}}.cmp`
+   - The LWC template file is: `{{componentName}}.html`
+   - You have access to supporting files such as controllers, helpers, CSS, blueprints, Jest tests (in `__tests__`), and UTAM page objects (in `__utam__`).
+
+6. **Important Notes:**
+   - This checklist is a comprehensive aid for developers to verify their work, not a judge of platform performance.
+   - The resulting ratings are confidence measures for the developer, not benchmarks.
+   - Each metric could, in the future, have a more detailed, dedicated tool for finer-grained verification, but avoid duplicating existing tools unless a true gap is identified.
+   - If you find that guidance is unclear or tools are not being applied consistently, note this as a potential process/tooling gap.
+
+## Completeness Metrics and Scoring
+
+- **Functional Parity**: Are all user-facing features, states, and flows from the Aura component present in the LWC?
+
+  - _Excellent_: All features and flows are present and work as intended.
+  - _Good_: Minor features or flows are missing or slightly altered.
+  - _Satisfactory_: Most features are present, but some notable differences exist.
+  - _Limited_: Several important features are missing or incomplete.
+  - _Poor_: Major features are missing or broken.
+  - _Missing_: No attempt at parity.
+
+- **Event Handling**: Are all events (custom, platform, UI) handled equivalently in the LWC?
+
+  - _Excellent_: All events are handled as in Aura.
+  - _Good_: Minor event handling differences.
+  - _Satisfactory_: Most events handled, some notable gaps.
+  - _Limited_: Several events missing or mishandled.
+  - _Poor_: Major event handling missing.
+  - _Missing_: No event handling present.
+
+- **Data Binding & State**: Are all data flows, attributes, and state transitions preserved and correctly mapped?
+
+  - _Excellent_: All data/state flows are preserved and correct.
+  - _Good_: Minor data/state differences.
+  - _Satisfactory_: Most data/state flows present, some gaps.
+  - _Limited_: Several data/state flows missing.
+  - _Poor_: Major data/state issues.
+  - _Missing_: No data/state mapping.
+
+- **UI/UX Parity**: Is the user interface (including accessibility, responsiveness, and SLDS usage) equivalent?
+
+  - _Excellent_: UI/UX matches or improves on Aura.
+  - _Good_: Minor UI/UX differences.
+  - _Satisfactory_: Most UI/UX present, some gaps.
+  - _Limited_: Several UI/UX issues.
+  - _Poor_: Major UI/UX issues.
+  - _Missing_: No UI/UX parity.
+
+- **Extensibility & Modularity**: Is the LWC designed for maintainability and future extension?
+
+  - _Excellent_: Highly modular and extensible.
+  - _Good_: Minor modularity/extensibility issues.
+  - _Satisfactory_: Adequate, but some concerns.
+  - _Limited_: Several modularity/extensibility issues.
+  - _Poor_: Major issues.
+  - _Missing_: Not modular/extensible.
+
+- **Error Handling**: Are all error states and recovery actions present and clear in the LWC?
+
+  - _Excellent_: All error handling present and clear.
+  - _Good_: Minor error handling gaps.
+  - _Satisfactory_: Most error handling present, some gaps.
+  - _Limited_: Several error handling issues.
+  - _Poor_: Major error handling missing.
+  - _Missing_: No error handling.
+
+- **Localization**: Are all labels/messages localized as in Aura?
+
+  - _Excellent_: All localization present.
+  - _Good_: Minor localization gaps.
+  - _Satisfactory_: Most localization present, some gaps.
+  - _Limited_: Several localization issues.
+  - _Poor_: Major localization missing.
+  - _Missing_: No localization.
+
+- **Security & Access Control**: Are there any regressions in data access or exposure?
+
+  - _Excellent_: No regressions, all controls present.
+  - _Good_: Minor security/access gaps.
+  - _Satisfactory_: Most controls present, some gaps.
+  - _Limited_: Several security/access issues.
+  - _Poor_: Major security/access issues.
+  - _Missing_: No security/access controls.
+
+- **Performance**: Is the LWC at least as performant, or improved, compared to Aura?
+
+  - _Excellent_: Performance matches or improves on Aura.
+  - _Good_: Minor performance differences.
+  - _Satisfactory_: Most performance present, some gaps.
+  - _Limited_: Several performance issues.
+  - _Poor_: Major performance issues.
+  - _Missing_: No performance consideration.
+
+- **Salesforce Best Practices**: Does the LWC follow modern Salesforce LWC and SLDS guidelines?
+
+  - _Excellent_: All best practices followed.
+  - _Good_: Minor best practice gaps.
+  - _Satisfactory_: Most best practices followed, some gaps.
+  - _Limited_: Several best practice issues.
+  - _Poor_: Major best practice issues.
+  - _Missing_: No best practices followed.
+
+- **Jest Test Coverage**: Are Jest unit tests present (usually in a `__tests__` folder) and do they cover key logic?
+
+  - _Excellent_: Comprehensive test coverage.
+  - _Good_: Minor test coverage gaps.
+  - _Satisfactory_: Most key logic covered, some gaps.
+  - _Limited_: Several test coverage issues.
+  - _Poor_: Major test coverage missing.
+  - _Missing_: No tests present.
+
+- **UTAM Page Objects**: Are UTAM page objects generated (usually in a `__utam__` folder) for UI automation?
+  - _Excellent_: Comprehensive UTAM coverage.
+  - _Good_: Minor UTAM coverage gaps.
+  - _Satisfactory_: Most key UI flows covered, some gaps.
+  - _Limited_: Several UTAM coverage issues.
+  - _Poor_: Major UTAM coverage missing.
+  - _Missing_: No UTAM page objects present.
+
+---
+
+## Example Output Structure
+
+```markdown
+# Aura to LWC Conversion Completeness Checklist
+
+- **Functional Parity**
+  - Description: Are all user-facing features, states, and flows from the Aura component present in the LWC?
+  - Rating: Good
+  - Justification: All major features are present, but one minor flow is missing.
+  - Comments: The save flow is slightly different, but overall parity is strong.
+
+- **Event Handling**
+  - Description: Are all events (custom, platform, UI) handled equivalently in the LWC?
+  - Rating: Excellent
+  - Justification: All events are handled as in Aura.
+
+... (repeat for each metric)
+
+# Summary
+
+Overall, the conversion is strong, with only minor gaps in functional parity and localization. Confidence in completeness is high.
+
+# Recommendations
+
+- Address the missing flow in functional parity.
+- Improve localization for error messages.
+```

package/skills/experience-aura-lwc-migrate/references/aura-values-expert.md

@@ -0,0 +1,67 @@
+## 💎 Values Expert Analysis Framework
+
+### Analysis Focus
+
+Analyze default values, configuration patterns, and value initialization in the Aura component.
+
+### Key Areas to Review
+
+#### 1. Default Value Analysis
+
+- Document all attribute default values and their significance
+- Identify initialization patterns and timing requirements
+- Note any computed default values or dynamic initialization
+- Check for environment-specific default value variations
+
+#### 2. Configuration Management
+
+- Analyze configuration attribute patterns and their usage
+- Document how configuration values affect component behavior
+- Identify any configuration validation or constraint patterns
+- Note any hierarchical configuration inheritance
+
+#### 3. Value Validation and Constraints
+
+- Document any validation logic for attribute values
+- Identify data type constraints and format requirements
+- Note any business rule validation patterns
+- Check for error handling of invalid values
+
+#### 4. Value Transformation
+
+- Analyze any value formatting or transformation logic
+- Document currency, date, or number formatting patterns
+- Identify any localization-specific value handling
+- Note any value normalization or sanitization
+
+### Migration Considerations
+
+- Aura default values need equivalent LWC property initialization
+- Configuration patterns may need LWC-specific approaches
+- Validation logic needs to be migrated to LWC methods
+- Value transformation may require different utility approaches
+
+### Additional knowledge
+
+#### Default Values analysis
+
+Your task is to make sure that default values of Aura attributes are assigned to JavaScript properties of LWC component.
+
+Review Aura component above and add default value of the attribute to the "what" property:
+
+1. If default value is a constant, add its type and value even if the value is empty string or null.
+   For example for <aura:attribute name="index" type="String" default="0">
+   """
+   "name": "index",
+   "what": "The index of the row being edited. Default value is string \"0\"."
+   """
+
+2. If default value points to a static resource, infer namespace and name of the resource, not its value.
+   For example for <aura:attribute name="label" default="{!$Label.myOrg.myLabelName}">, default value should be mentioned like so:
+   """
+   "name": "label",
+   "what": "The label next to input. Default value is a label from namespace \"myOrg\" with the name \"myLabelName\"".
+   """
+
+- For each issue found, provide a separate, detailed report.
+- Keep issues concise, avoid duplicated issues or unnecessary or non-applicable problems.

package/skills/experience-content-media-search/SKILL.md

@@ -3,7 +3,16 @@ name: experience-content-media-search
 description: "Searches for and retrieves existing visual media (images, logos, icons, photos, graphics, banners, thumbnails, hero images, backgrounds) from sources such as Salesforce CMS, Data 360 or any other source. Use this skill ANY TIME a user request involves finding, searching, getting, fetching, retrieving, grab, looking up, locating media. NEVER call search_media_cms_channels, search_electronic_media tools directly — always go through this skill first. This skill must be activated before any tool is used for media search or retrieval, without exception.  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 about brand search, to generate NEW images with AI, or edit existing images."
 compatibility: "Requires search_media_cms_channels and/or search_electronic_media MCP tools"
 metadata:
-  version: "1.0"
+  version: "1.1"
+  relatedSkills:
+    - "experience-content-media-stock-image-search"
+  mcpTools:
+    content-readonly:
+      tools:
+        - search_media_cms_channels
+        - search_electronic_media
+        - get_channels
+      semver: "^1.0.0"
 ---
 
 # Media Search
@@ -26,6 +35,7 @@ Universal routing skill for searching and retrieving existing images and media.
 - Create graphics or designs from scratch
 - Edit or modify existing images
 - Build custom visuals or diagrams
+- Search for stock photography or royalty-free images (use `experience-content-media-stock-image-search`)
 
 ## Before You Search
 
@@ -186,8 +196,7 @@ After the user selects an option, execute the corresponding search method below.
     "searchKeyword": "keyword1 OR keyword2 OR keyword3",
     "taxonomyExpression": "{\"OR\": [\"Taxonomy1\", \"Taxonomy2\"]}",
     "searchLanguage": "en_US",
-    "channelIds": "",
-    "channelType": "PublicUnauthenticated",
+    "contentAccessScope": "Public",
     "contentTypeFqn": "sfdc_cms__image",
     "pageOffset": 0,
     "searchLimit": 5
@@ -199,8 +208,7 @@ After the user selects an option, execute the corresponding search method below.
 - `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"`
+- `contentAccessScope`: Always `"Public"` (covers both public-unauthenticated and public Experience Cloud site channels)
 - `contentTypeFqn`: Always `"sfdc_cms__image"`
 - `pageOffset`: Start at `0`, increment by `searchLimit` for pagination
 - `searchLimit`: Default `5`, adjust if user requests more
@@ -214,8 +222,7 @@ Query: "luxury apartment with river view"
     "searchKeyword": "apartment OR villa OR penthouse OR residence",
     "taxonomyExpression": "{\"OR\": [\"Luxury\", \"Premium\", \"Waterfront\", \"Riverside\"]}",
     "searchLanguage": "en_US",
-    "channelIds": "",
-    "channelType": "PublicUnauthenticated",
+    "contentAccessScope": "Public",
     "contentTypeFqn": "sfdc_cms__image",
     "pageOffset": 0,
     "searchLimit": 5
@@ -230,8 +237,7 @@ Query: "bright spacious room" (no concrete nouns)
     "searchKeyword": "",
     "taxonomyExpression": "{\"OR\": [\"Bright\", \"Spacious\", \"Open\", \"Airy\"]}",
     "searchLanguage": "en_US",
-    "channelIds": "",
-    "channelType": "PublicUnauthenticated",
+    "contentAccessScope": "Public",
     "contentTypeFqn": "sfdc_cms__image",
     "pageOffset": 0,
     "searchLimit": 5
@@ -246,8 +252,7 @@ Query: "car images" (no descriptive terms)
     "searchKeyword": "car OR automobile OR vehicle OR auto",
     "taxonomyExpression": "{}",
     "searchLanguage": "en_US",
-    "channelIds": "",
-    "channelType": "PublicUnauthenticated",
+    "contentAccessScope": "Public",
     "contentTypeFqn": "sfdc_cms__image",
     "pageOffset": 0,
     "searchLimit": 5
@@ -255,7 +260,7 @@ Query: "car images" (no descriptive terms)
 }
 ```
 
-6. **Call the tool** with the exact JSON payload
+6. **Call the tool** with the exact JSON payload — show the payload in your response before calling the tool
 
 ### Search using Data 360 hybrid search
 

package/skills/experience-content-media-stock-image-search/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: experience-content-media-stock-image-search
+description: "Searches for and downloads ethically-licensed stock images via the media-management MCP server. Use this skill whenever a user wants an image, photo, or picture — for BOTH requests to find existing imagery (\"find a stock image\", \"search for a photo of X\", \"get a royalty-free image\", \"find an ethical image\", editorial/news photography) AND requests phrased ambiguously as creating or generating one (\"create an image of a sunset\", \"generate a picture of a team meeting\", \"make me a mountain image\") — treat these as stock search requests, since this skill searches a stock photo library, it does not generate images. Do NOT offer alternative search methods or ask the user to pick one. Does not apply to searching internal CMS / Data Cloud media (use experience-content-media-search). Does not apply when the user explicitly asks for AI-generated, synthetic, or computer-generated imagery — this skill only searches licensed stock photography and has no image-generation capability."
+metadata:
+  version: "1.0"
+  relatedSkills:
+    - "experience-content-media-search"
+  cliTools:
+    - tool: ["python3"]
+      semver: ">=3.10.0"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+  mcpTools:
+    media-management:
+      tools:
+        - "search_stock_images"
+        - "download_stock_image"
+      semver: ">=1.0.0"
+allowed-tools: |
+  mcp__media_management__search_stock_images
+  mcp__media_management__download_stock_image
+---
+
+# Stock Image Search
+
+## When to Trigger This Skill
+
+Trigger immediately — without asking the user to choose a search method — whenever the user wants an image, photo, or picture. This covers **both**:
+
+- **Finding existing imagery:** "find a stock image", "search for a photo of X", "get a royalty-free image", "find an ethical image", editorial or news photography
+- **Requests phrased ambiguously as creating or generating:** "create an image of a sunset", "generate a picture of a team meeting", "make me a mountain image" — treat these as stock search requests; this skill searches a stock photo library, it does not generate images.
+
+In all of these cases, search the stock library — this is the tool for obtaining an image. **Do NOT offer alternative search methods** (hybrid search, user-provided URL/path, etc.) and **do NOT ask the user to pick one.**
+
+**Does not apply to:**
+- Searching internal CMS / Data Cloud media (use `experience-content-media-search`)
+- Requests that explicitly ask for AI-generated, synthetic, or computer-generated imagery — this skill only searches licensed stock photography and has no image-generation capability
+
+---
+
+## Step 1 — Search
+
+**MCP tool:** `search_stock_images` (server: `media-management`)
+**Timeout:** 30 seconds
+
+| Parameter    | Required | Default     | Notes                                                                              |
+|--------------|----------|-------------|------------------------------------------------------------------------------------|
+| `query`      | ✅ Yes   | —           | Natural language search phrase (e.g. "sunset over ocean", "business meeting"), max 500 chars |
+| `searchType` | No       | `Creative`  | `Creative` (royalty-free stock), `Editorial` (rights-managed news/event imagery)   |
+| `orientation`| No       | _(none)_    | `Horizontal`, `Vertical`, `Square`, `PanoramicHorizontal`, `PanoramicVertical`     |
+| `sortOrder`  | No       | `BestMatch` | `BestMatch`, `MostPopular`, `Newest`                                               |
+| `pageSize`   | No       | `5`         | 1–100                                                                              |
+| `page`       | No       | `1`         | 1-indexed, must be >= 1                                                            |
+
+**Smart keyword extraction:** If the query is longer than 20 words or returns no results, the tool automatically extracts short keyword phrases via LLM and retries. The `effectiveQuery` field in the response shows what was actually sent to the search service (`null` if the original query was used unchanged).
+
+**Response fields:**
+
+| Field             | Notes                                                                                        |
+|-------------------|----------------------------------------------------------------------------------------------|
+| `images[]`        | List of results (see item fields below)                                                      |
+| `totalCount`      | Total matches across all pages                                                               |
+| `page`            | Current page (1-indexed)                                                                     |
+| `pageSize`        | Results per page                                                                             |
+| `searchRequestId` | Internal correlation ID. Server-managed; not passed back through the MCP download tool. Safe to surface in debug output if useful. |
+| `effectiveQuery`  | Keywords actually sent to the search service. Null if the original query was used unchanged. |
+| `errorMessage`    | Non-null if the search failed                                                                |
+
+**Each `images[]` item:**
+
+| Field          | Notes                                                                |
+|----------------|----------------------------------------------------------------------|
+| `assetId`      | Stock asset ID — required for download. Safe to display alongside the result if useful. |
+| `title`        | Image title                                                          |
+| `caption`      | Image description                                                    |
+| `thumbnailUrl` | Small preview URL — use for grid display                             |
+| `previewUrl`   | Larger comp/preview URL — use for tile display                       |
+| `width`        | Max width in pixels                                                  |
+| `height`       | Max height in pixels                                                 |
+| `licenseModel` | e.g. `royaltyfree`, `rightsmanaged`                                  |
+| `artist`       | Contributor/artist name                                              |
+| `collection`   | Collection name                                                      |
+
+---
+
+## Step 2 — Present Results, then STOP
+
+Render a numbered list with an inline thumbnail for each result, using `thumbnailUrl` for the image and `previewUrl` as the click-through link (clicking the thumbnail opens the full preview in the browser):
+
+```text
+1. [![<title>](<thumbnailUrl>)](<previewUrl>)
+   **<title>** — <artist>, <width>×<height>, <licenseModel>
+2. ...
+```
+
+This is standard markdown image-in-link syntax (`[![alt](thumbnailUrl)](previewUrl)`) — it renders an actual thumbnail, not just a text link, and clicking it navigates to `previewUrl`. If a client doesn't render markdown images, this degrades gracefully to a linked title.
+
+Prefix the list with `Searched for: <effectiveQuery>` only if `effectiveQuery` is non-null and differs from the user's original query.
+
+**End the turn here. Do not auto-download, do not write files, do not ask a follow-up question.** Agentforce injects its own selection UI — a question or auto-select causes a duplicate "double ask". Do not pick a result on behalf of the user.
+
+**Non-interactive mode** (scheduled/headless, no user present): pick `images[0]` from the results and note the auto-selection in the report. Then proceed directly to Step 3.
+
+---
+
+## Step 3 — Download (billed)
+
+⚠️ **Each call licenses the image and spends a stock-image download credit. Only invoke after the user explicitly selects an image (or in non-interactive mode, as noted above).**
+
+**Before calling `download_stock_image`, verify:**
+- [ ] User has explicitly named or numbered the image they want (or non-interactive mode is confirmed)
+- [ ] This is not an automatic retry of a previous download
+
+**MCP tool:** `download_stock_image` (server: `media-management`)
+**Timeout:** 60 seconds
+
+| Parameter   | Required | Default | Notes                                                                                              |
+|-------------|----------|---------|----------------------------------------------------------------------------------------------------|
+| `assetId`   | ✅ Yes   | —       | Stock asset ID from the prior `search_stock_images` result, max 50 chars                           |
+| `size`      | No       | `comp`  | `comp` (web-quality composite, default), `medium_jpg`, `largest` (full res, can exceed 100 MB), max 50 chars |
+
+Use `largest` only when the user explicitly asks for full/original resolution.
+
+**Response fields:**
+
+| Field                        | Notes                                                                 |
+|------------------------------|-----------------------------------------------------------------------|
+| `assetId`                    | Stock asset ID that was downloaded                                    |
+| `managedContentBodyId`       | Salesforce record ID where image bytes are stored                     |
+| `parentContentGenAiOutputId` | Record tracking the download request                                  |
+| `childContentGenAiOutputId`  | Record linking the request to the persisted body                      |
+| `byteCount`                  | Size of the persisted image in bytes                                  |
+| `format`                     | Resolved image format (e.g. `jpg`, `png`, `eps`, `tiff`, `svg`)       |
+| `url`                        | **URL to the persisted image** — use this to download or preview it   |
+
+---
+
+## Step 4 — Download to Client and Preview
+
+After a successful `download_stock_image` call, download the image locally and open it in VS Code.
+
+**You MUST use `download-stock-image.py` for this. Do not use `curl`, `wget`, or any other tool.**
+
+```bash
+python3 scripts/download-stock-image.py \
+  --url "<url from download response>" \
+  --id "<assetId>" \
+  --format "<format from download response>" \
+  --preview
+```
+
+The script retrieves org credentials via the `sf` CLI (`sf config get target-org` and `sf org auth show-access-token`), downloads the image with `Authorization: Bearer <accessToken>` to `stockimages/<assetId>.<format>`, and opens it in VS Code if `--preview` is passed.
+
+Pass `--output-dir <path>` to override the default `stockimages/` directory.
+
+**Never resize or post-process the image.** Use CSS (`width`, `height`, `object-fit`) to control display dimensions.
+
+**Vector/binary formats (`eps`, `tiff`):** always pass the exact `format` returned by the download response — never substitute a format like `jpg` to work around a validation error; the file bytes won't match the extension and the file will appear corrupted. VS Code cannot render `eps`/`tiff` previews, so the script skips `--preview` for those formats automatically and still reports the saved path.
+
+---
+
+## Step 5 — Report Back
+
+After a successful download, tell the user:
+- Image title and artist
+- Local path to the saved image (printed by the script)
+- `managedContentBodyId`
+- Attribution: `{artist} · {collection}` (use the attribution string returned by the download response when present)
+
+---
+
+## Fallbacks & Errors
+
+| Situation                          | Action                                                                       |
+|------------------------------------|------------------------------------------------------------------------------|
+| `errorMessage` non-null in search  | Show it; suggest a simpler query or different `searchType`/`orientation`     |
+| `images` empty                     | Suggest broader keywords; try switching `Editorial` vs `Creative`            |
+| `effectiveQuery` differs           | Inform user what the search service actually received                        |
+| MCP tools unavailable              | Use the placeholder URL below — do not download or save                      |
+| Download fails                     | Show error; do NOT retry automatically — confirm with user first (each retry is billed) |
+
+---
+
+## Placeholder
+
+If `search_stock_images` and `download_stock_image` are both unavailable, use this URL directly as `src` or CSS `url()`:
+
+```text
+https://cdn.scs.static.lightning.force.com/content/assets/d5222d4a11e6c2b735152d7eea824ce4/placeholder.svg
+```
+
+**Placeholder policy:** There is only one placeholder URL. Do not download it, modify it, or generate alternative placeholders using Python, ImageMagick, or any other tool. If the user asks for a placeholder of a specific size or format, tell them only this URL is available and direct them to use CSS to scale it at the point of use.