@salesforce/afv-skills 1.29.0 → 1.31.0

package/skills/platform-flexipage-generate/references/xml_rules.md

@@ -0,0 +1,335 @@
+# Critical XML Rules & Deployment Errors
+
+## Contents
+
+0. [STOP — Read Before Writing ANY componentInstance](#stop--read-before-writing-any-componentinstance)
+1. [Property Value Encoding](#1-property-value-encoding-most-common-error)
+2. [Field References](#2-field-references)
+3. [Region vs Facet Types](#3-region-vs-facet-types)
+4. [itemInstances — ONE Child Per Wrapper](#4-iteminstances--one-child-per-wrapper-critical)
+5. [Unique Identifiers and Region Names](#5-unique-identifiers-and-region-names-critical---prevents-duplicate-errors)
+6. [Correct Element Names](#6-correct-element-names-critical--prevents-invalid-xml-errors)
+7. [Common Deployment Errors](#common-deployment-errors)
+
+---
+
+## STOP — Read Before Writing ANY componentInstance
+
+**The element name is `<componentInstanceProperties>`, NEVER `<properties>`.**
+
+```xml
+<!-- WRONG — WILL FAIL DEPLOYMENT -->
+<componentInstance>
+    <properties>
+        <name>label</name>
+        <value>Hello</value>
+    </properties>
+    <componentName>flexipage:fieldSection</componentName>
+    <identifier>id1</identifier>
+</componentInstance>
+
+<!-- CORRECT — the ONLY valid element name -->
+<componentInstance>
+    <componentInstanceProperties>
+        <name>label</name>
+        <value>Hello</value>
+    </componentInstanceProperties>
+    <componentName>flexipage:fieldSection</componentName>
+    <identifier>id1</identifier>
+</componentInstance>
+```
+
+**There is no `<properties>` element in FlexiPage XML. It does not exist. Every time you write a property inside `<componentInstance>`, you MUST write `<componentInstanceProperties>`. If you find yourself typing `<properties>`, STOP and correct it to `<componentInstanceProperties>`.**
+
+---
+
+## 1. Property Value Encoding (MOST COMMON ERROR)
+
+**Any property value with HTML/XML characters MUST be manually encoded in the following order** (wrong order causes double-encoding corruption):
+
+```text
+1. & → &amp;   (FIRST! Encode this before others)
+2. < → &lt;
+3. > → &gt;
+4. " → &quot;
+5. ' → &apos;
+```
+
+**Wrong:**
+```xml
+<value><b>Important</b> text</value>
+```
+
+**Correct:**
+```xml
+<value>&lt;b&gt;Important&lt;/b&gt; text</value>
+```
+
+**Check your XML:** Search for `<value>` tags - they should never contain raw `<` or `>` characters.
+
+## 2. Field References
+
+Use `Record.{FieldApiName}` — never `{ObjectName}.{FieldApiName}` (Salesforce resolves from Record, not object name).
+
+```xml
+<!-- Correct -->
+<fieldItem>Record.Name</fieldItem>
+
+<!-- Wrong -->
+<fieldItem>Account.Name</fieldItem>
+```
+
+## 3. Region vs Facet Types
+
+**Template Regions** (header, main, sidebar):
+```xml
+<name>header</name>
+<type>Region</type>
+```
+
+**Component Facets** (internal slots like fieldSection columns):
+```xml
+<name>Facet-12345</name>
+<type>Facet</type>
+```
+
+**Rule:** If it's a template region name → `Region`. If it's a component slot → `Facet`.
+
+## 4. itemInstances — ONE Child Per Wrapper (CRITICAL)
+
+**Each `<itemInstances>` can contain exactly ONE child element** — either one `<componentInstance>` OR one `<fieldInstance>`. Never put multiple children inside a single `<itemInstances>`.
+
+```xml
+<!-- WRONG — multiple componentInstance in one itemInstances -->
+<itemInstances>
+    <componentInstance>
+        <componentName>flexipage:field</componentName>
+        <identifier>field1</identifier>
+    </componentInstance>
+    <componentInstance>
+        <componentName>flexipage:field</componentName>
+        <identifier>field2</identifier>
+    </componentInstance>
+</itemInstances>
+
+<!-- CORRECT — each componentInstance in its own itemInstances -->
+<itemInstances>
+    <componentInstance>
+        <componentName>flexipage:field</componentName>
+        <identifier>field1</identifier>
+    </componentInstance>
+</itemInstances>
+<itemInstances>
+    <componentInstance>
+        <componentName>flexipage:field</componentName>
+        <identifier>field2</identifier>
+    </componentInstance>
+</itemInstances>
+```
+
+### fieldInstance Structure
+
+Every fieldInstance requires:
+```xml
+<itemInstances>
+   <fieldInstance>
+      <fieldInstanceProperties>
+         <name>uiBehavior</name>
+         <value>none</value> <!-- none|readonly|required -->
+      </fieldInstanceProperties>
+      <fieldItem>Record.FieldName__c</fieldItem>
+      <identifier>RecordFieldName_cField</identifier>
+   </fieldInstance>
+</itemInstances>
+```
+
+**Valid `uiBehavior` values (lowercase only):**
+
+| Value | Meaning |
+|-------|---------|
+| `none` | Field respects standard editability settings (default) |
+| `readonly` | Field is permanently locked on this page |
+| `required` | Field must be filled out before saving on this page |
+
+**Rules:**
+- Each `<itemInstances>` gets exactly ONE child (`<componentInstance>` or `<fieldInstance>`)
+- fieldInstance must have `fieldInstanceProperties` with `uiBehavior`
+- Use `Record.{Field}` format
+- There is NO `edit` value — use `none` for standard editable fields
+
+## 5. Unique Identifiers and Region Names (CRITICAL - PREVENTS DUPLICATE ERRORS)
+
+**EVERY identifier and region/facet name MUST be unique across the entire FlexiPage file.**
+
+- **NEVER create two `<flexiPageRegions>` blocks with the same `<name>`**
+- **If multiple components belong to same facet, combine them in ONE region with multiple `<itemInstances>`**
+- **NEVER reuse the same `<identifier>` value**
+- **Always read entire file first and extract ALL existing identifiers and names**
+- **Element order inside `<flexiPageRegions>`**: `<itemInstances>` FIRST, then `<mode>` (if needed), then `<name>`, then `<type>` — NEVER put `<name>`/`<type>` before `<itemInstances>`
+
+**Wrong - This WILL FAIL with duplicate name error:**
+```xml
+<!-- First field section in detail tab -->
+<flexiPageRegions>
+   <itemInstances>
+      <componentInstance>
+         <identifier>flexipage_property_details_fieldSection</identifier>
+         ...
+      </componentInstance>
+   </itemInstances>
+   <name>detailTabContent</name>  <!-- WRONG: DUPLICATE NAME -->
+   <type>Facet</type>
+</flexiPageRegions>
+
+<!-- Second field section in detail tab -->
+<flexiPageRegions>
+   <itemInstances>
+      <componentInstance>
+         <identifier>flexipage_pricing_fieldSection</identifier>
+         ...
+      </componentInstance>
+   </itemInstances>
+   <name>detailTabContent</name>  <!-- WRONG: DUPLICATE NAME - DEPLOYMENT FAILS -->
+   <type>Facet</type>
+</flexiPageRegions>
+```
+
+**Correct - Combine itemInstances in ONE region:**
+```xml
+<!-- Both field sections in same detail tab facet -->
+<flexiPageRegions>
+   <itemInstances>
+      <componentInstance>
+         <identifier>flexipage_property_details_fieldSection</identifier>
+         ...
+      </componentInstance>
+   </itemInstances>
+   <itemInstances>
+      <componentInstance>
+         <identifier>flexipage_pricing_fieldSection</identifier>
+         ...
+      </componentInstance>
+   </itemInstances>
+   <name>detailTabContent</name>  <!-- CORRECT: ONE REGION, MULTIPLE COMPONENTS -->
+   <type>Facet</type>
+</flexiPageRegions>
+```
+
+**When to combine vs separate:**
+- **Combine**: Components that logically belong to same tab/section (e.g., multiple field sections in detail tab)
+- **Separate**: Components that belong to different tabs/sections (e.g., `detailTabContent` vs `relatedTabContent`)
+
+---
+
+## 6. Correct Element Names (CRITICAL — PREVENTS INVALID XML ERRORS)
+
+**FlexiPage XML uses specific element names. Common LLM hallucinations use WRONG names that cause deployment failures.**
+
+| WRONG (do NOT use) | CORRECT |
+|---|---|
+| `<entityType>` | `<sobjectType>` |
+| `<properties>` | `<componentInstanceProperties>` |
+| `<regions>` | `<flexiPageRegions>` |
+| `<components>` | `<itemInstances>` |
+| `<innerComponents>` | (does not exist — use facets for nesting) |
+| `<fieldItems>` | `<itemInstances>` containing `<fieldInstance>` |
+| `<template>value</template>` | `<template><name>value</name></template>` |
+| `<parentFlexiPage>flexipage:templateName</parentFlexiPage>` | `<parentFlexiPage>flexipage__default_rec_L</parentFlexiPage>` |
+
+**Do NOT invent elements or component names:**
+
+Only use component names discovered through the 3-tier discovery process or present in the template from CLI. Do NOT add any XML element that is not present in the template structure from the CLI template. If a component name did not come from discovery or the CLI template.
+
+| WRONG (do NOT use) | Why / What to use instead |
+|---|---|
+| `<apiVersion>` | Not a FlexiPage element — API version lives in `sfdx-project.json` |
+| `<description>` | Not a FlexiPage element — use `<masterLabel>` for the page name |
+| `flexipage:tabs` | Does not exist — use `flexipage:tabset` + `flexipage:tab` in facets |
+| `flexipage:tabset2` | Does not exist — correct name is `flexipage:tabset` |
+| `flexipage:facet` | Does not exist — use `flexipage:column` with `body` property |
+| `flexipage:fields` | Does not exist — use individual `fieldInstance` elements in a field facet |
+| `<type>String</type>` inside `componentInstanceProperties` | Remove — only valid `<type>` value is `decorator`, and only for UtilityBar pages |
+
+**Correct top-level FlexiPage structure (element order):**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<FlexiPage xmlns="http://soap.sforce.com/2006/04/metadata">
+    <flexiPageRegions>...</flexiPageRegions>
+    <masterLabel>Page Name</masterLabel>
+    <parentFlexiPage>flexipage__default_rec_L</parentFlexiPage>
+    <sobjectType>Account</sobjectType>
+    <template>
+        <name>flexipage:recordHomeTemplateDesktop</name>
+    </template>
+    <type>RecordPage</type>
+</FlexiPage>
+```
+
+**Correct componentInstance structure:**
+```xml
+<componentInstance>
+    <componentInstanceProperties>
+        <name>propertyName</name>
+        <value>propertyValue</value>
+    </componentInstanceProperties>
+    <componentName>lightning:card</componentName>
+    <identifier>unique_id_1</identifier>
+</componentInstance>
+```
+
+**`<componentInstanceProperties>` children — `<name>`, `<value>`, and optionally `<type>`:**
+
+```xml
+<!-- WRONG — "String", "Facet", etc. are NOT valid <type> values -->
+<componentInstanceProperties>
+    <name>fieldApiName</name>
+    <type>String</type>
+    <value>Record.Name</value>
+</componentInstanceProperties>
+
+<!-- CORRECT — omit <type> for standard properties (most cases) -->
+<componentInstanceProperties>
+    <name>fieldApiName</name>
+    <value>Record.Name</value>
+</componentInstanceProperties>
+
+<!-- CORRECT — <type>decorator</type> ONLY for UtilityBar component decorators -->
+<componentInstanceProperties>
+    <name>panelHeight</name>
+    <type>decorator</type>
+    <value>480</value>
+</componentInstanceProperties>
+```
+
+**`<type>` rules:**
+- If omitted (default): the property applies to the Lightning component itself
+- If `decorator`: the property applies to the **component decorator** (a wrapper that adds capabilities like height/width when opened)
+- The ONLY valid value is `decorator` — never `String`, `Facet`, `Integer`, etc.
+- Component decorators are ONLY supported on **UtilityBar** page types — do NOT use `<type>decorator</type>` on RecordPage, AppPage, or HomePage
+
+**Nesting is done via facets, NOT via inner elements.** Components that contain other components reference a facet name in their properties; the facet is a sibling `<flexiPageRegions>` with `<type>Facet</type>`.
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| "Element regions invalid in FlexiPage" | Used `<regions>` instead of `<flexiPageRegions>` | Replace with `<flexiPageRegions>` |
+| "Element components invalid in FlexiPageRegion" | Used `<components>` instead of `<itemInstances>` | Replace with `<itemInstances>` |
+| "couldn't retrieve design time component information" | Used hallucinated component name (`flexipage:tabs`, `flexipage:tabset2`) | Use `flexipage:tabset` — see `identifiers_and_regions.md` for the full 3-layer tab pattern |
+
+---
+
+## Common Deployment Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| "We couldn't retrieve or load the information on the field" | Invalid field API name — field doesn't exist or has incorrect spelling | Use MCP tools or describe commands to discover valid fields |
+| "Invalid field reference" | Used `ObjectName.Field` instead of `Record.Field` | Change to `Record.{FieldApiName}` |
+| "Element componentInstance is duplicated at this location in type ItemInstance" | Multiple `<componentInstance>` in one `<itemInstances>` | Each `<componentInstance>` needs its own `<itemInstances>` wrapper |
+| "Element fieldInstance is duplicated" | Multiple fieldInstances in one `<itemInstances>` | Each fieldInstance needs its own `<itemInstances>` wrapper |
+| "Missing fieldInstanceProperties" | No uiBehavior specified | Add `fieldInstanceProperties` with `uiBehavior` |
+| "Unused Facet" | Facet defined but not referenced by any component | Remove Facet or reference it in a component property |
+| "XML parsing error" | Unencoded HTML/XML in property values | Encode `<`, `>`, `&`, `"`, `'` in all `<value>` tags |
+| "Cannot create component with namespace" | Invalid page name (used `__c` suffix) | Use `Volunteer_Record_Page` not `Volunteer__c_Record_Page` |
+| "Region specifies mode that parent doesn't support" | Added `<mode>` to a region that doesn't support it | Only use `<mode>` where required (e.g., `<mode>Replace</mode>` in `detailTabContent` for Dynamic Forms) |
+| "We couldn't retrieve the design time component information for component X" | Hallucinated component name (e.g., `flexipage:tabs`, `flexipage:tabset2`) | Use correct component name — see Section 6 table and `identifiers_and_regions.md` for valid patterns |
+| "'String' is not a valid value for the enum 'ComponentInstancePropertyTypeEnum'" | Used invalid `<type>` value (e.g., `String`, `Facet`, `Integer`) inside `<componentInstanceProperties>` | Remove `<type>` entirely — the only valid value is `decorator`, and only for UtilityBar page types |
+| "Element apiVersion invalid at this location in type FlexiPage" | Added `<apiVersion>` to FlexiPage XML | Remove — API version belongs in `sfdx-project.json`, not in FlexiPage metadata |

package/skills/platform-flexipage-generate/scripts/resolve-component-instructions.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+# resolve-component-instructions.sh — Resolve the instructions file path for a component.
+#
+# Usage: scripts/resolve-component-instructions.sh <componentDefinition>
+#
+# Arguments:
+#   componentDefinition — Component FQN in colon format (e.g., "flexipage:fieldSection")
+#
+# Output: The path to the instructions file if it exists, or empty string if not found.
+#
+# Examples:
+#   scripts/resolve-component-instructions.sh "record_flexipage:dynamicHighlights"
+#   → references/record_flexipage_dynamicHighlights.md
+#
+#   scripts/resolve-component-instructions.sh "flexipage:fieldSection"
+#   → references/flexipage_fieldSection.md
+#
+#   scripts/resolve-component-instructions.sh "c:expenseTracker"
+#   → (empty — file does not exist)
+
+set -euo pipefail
+
+COMPONENT="${1:-}"
+
+if [ -z "$COMPONENT" ]; then
+  echo "Usage: $0 <componentDefinition>" >&2
+  exit 1
+fi
+
+# Derive filename: replace ':' with '_', append .md
+FILENAME=$(echo "$COMPONENT" | sed 's/:/_/g').md
+
+# Resolve path relative to the skill directory
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SKILL_DIR="$(dirname "$SCRIPT_DIR")"
+FILEPATH="$SKILL_DIR/references/$FILENAME"
+
+if [ -f "$FILEPATH" ]; then
+  echo "references/$FILENAME"
+else
+  echo ""
+fi

package/skills/platform-flexipage-generate/scripts/scan-lwc-components.sh

@@ -0,0 +1,113 @@
+#!/bin/bash
+# scan-lwc-components.sh — Scan local SFDX project for LWC components matching a query.
+#
+# Usage: scripts/scan-lwc-components.sh <query> [packageDirectory]
+#
+# Arguments:
+#   query             — User intent keywords (e.g., "expense tracker")
+#   packageDirectory  — SFDX package directory path (default: read from sfdx-project.json)
+#
+# Output: Ranked JSON array of matches with confidence scores.
+#   [{"name": "expenseTracker", "score": 75, "confidence": "high"}]
+#
+# Confidence tiers:
+#   high   (≥70%): auto-select, confirm with user
+#   medium (40-69%): present ranked list for user selection
+#   low    (<40%): skip, proceed to Tier 2
+
+set -euo pipefail
+
+QUERY="${1:-}"
+PKG_DIR="${2:-}"
+
+if [ -z "$QUERY" ]; then
+  echo "Usage: $0 <query> [packageDirectory]" >&2
+  exit 1
+fi
+
+# Resolve package directory from sfdx-project.json if not provided
+if [ -z "$PKG_DIR" ]; then
+  if [ -f "sfdx-project.json" ]; then
+    PKG_DIR=$(python3 -c "
+import json, sys
+with open('sfdx-project.json') as f:
+    data = json.load(f)
+    dirs = data.get('packageDirectories', [])
+    if dirs:
+        print(dirs[0].get('path', 'force-app'))
+    else:
+        print('force-app')
+" 2>/dev/null || echo "force-app")
+  else
+    PKG_DIR="force-app"
+  fi
+fi
+
+# Check if package directory exists
+if [ ! -d "$PKG_DIR" ]; then
+  echo "[]"
+  exit 0
+fi
+
+# Tokenize query: lowercase, split on spaces
+IFS=' ' read -ra QUERY_TOKENS <<< "$(echo "$QUERY" | tr '[:upper:]' '[:lower:]')"
+
+# Find all LWC component directories
+RESULTS="["
+FIRST=true
+
+while IFS= read -r dir; do
+  COMP_NAME=$(basename "$dir")
+
+  # Tokenize camelCase component name: split on uppercase boundaries → lowercase
+  COMP_TOKENS=$(echo "$COMP_NAME" | sed 's/\([a-z]\)\([A-Z]\)/\1 \2/g' | tr '[:upper:]' '[:lower:]')
+  IFS=' ' read -ra TOKENS <<< "$COMP_TOKENS"
+  TOTAL=${#TOKENS[@]}
+
+  if [ "$TOTAL" -eq 0 ]; then
+    continue
+  fi
+
+  # Count matched tokens
+  MATCHED=0
+  for qt in "${QUERY_TOKENS[@]}"; do
+    for ct in "${TOKENS[@]}"; do
+      if [ "$qt" = "$ct" ]; then
+        MATCHED=$((MATCHED + 1))
+        break
+      fi
+    done
+  done
+
+  # Calculate score
+  SCORE=$(( (MATCHED * 100) / TOTAL ))
+
+  # Determine confidence tier
+  if [ "$SCORE" -ge 70 ]; then
+    CONFIDENCE="high"
+  elif [ "$SCORE" -ge 40 ]; then
+    CONFIDENCE="medium"
+  else
+    CONFIDENCE="low"
+  fi
+
+  # Only include medium and high confidence matches
+  if [ "$SCORE" -ge 40 ]; then
+    if [ "$FIRST" = true ]; then
+      FIRST=false
+    else
+      RESULTS+=","
+    fi
+    RESULTS+="{\"name\":\"$COMP_NAME\",\"score\":$SCORE,\"confidence\":\"$CONFIDENCE\"}"
+  fi
+done < <(find "$PKG_DIR" -path "*/lwc/*" -type d -maxdepth 5 | grep -v "__tests__")
+
+RESULTS+="]"
+
+# Sort by score descending (using python for JSON sorting)
+echo "$RESULTS" | python3 -c "
+import json, sys
+data = json.load(sys.stdin)
+data.sort(key=lambda x: x['score'], reverse=True)
+print(json.dumps(data, indent=2))
+" 2>/dev/null || echo "$RESULTS"

package/skills/platform-metadata-api-context-get/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: platform-metadata-api-context-get
-description: "Salesforce Metadata API reference for creating, understanding, or modifying metadata XML files (.object-meta.xml, .flow-meta.xml, etc.) and any of 604 metadata types (CustomObject, Flow, ApexClass, ApexTrigger, Profile, PermissionSet, Layout, ValidationRule, RecordType, EmailTemplate, ...). Use for questions about a type's fields or XML format, or Salesforce DX project structure (force-app/main/default). TRIGGER when: authoring or editing any *-meta.xml file, asking what fields/format a metadata type has, or whenever 'Salesforce metadata' or 'sfdx project' is mentioned. DO NOT TRIGGER when: SOQL/DML/runtime sObject access (use the Enterprise API skill), Tooling API developer records (ApexExecutionOverlayAction, TraceFlag), or non-XML logic (Apex code, LWC JS, Visualforce controllers)."
+description: "REQUIRED companion for Salesforce metadata generation — load this schema/API-context skill in the SAME turn as ANY metadata generation skill; if you load a generator, you ALSO load this. Use it whenever you create, generate, add, edit, or author metadata or a *-meta.xml file: custom object, custom field, formula field, picklist, lookup, master-detail, validation rule, permission set, profile, custom tab, lightning record page, flexipage, list view, custom application, flow, layout, record type, sharing rules, report, and 604 Metadata API types. It provides the authoritative schema, fields, field properties, required flags, allowed enum values, and XML structure so generated *-meta.xml deploys cleanly — skipping it causes hallucinated element names and deploy failures. Trigger on *-meta.xml, metadata schema, api context, 'Salesforce metadata', or 'sfdx project'. DO NOT use for SOQL, DML, runtime sObject access, or Tooling API records."
 metadata:
   version: "1.0"
   minApiVersion: "67.0"
@@ -53,12 +53,15 @@ To get information about a specific metadata type:
 
 ### Example Queries (Section-Specific)
 
-- ✅ "Show me only the 'fields' section from CustomObject.json"
-- ✅ "What fields are in the 'fields' section of Profile.json?"
-- ✅ "Load the 'description' and 'fields' sections from Flow.json"
-- ✅ "Give me just the 'declarative_metadata_sample_definition' from ApexClass.json"
-- ❌ "Show me the CustomObject metadata type" (too broad - entire file)
-- ❌ "Load CustomObject.json" (includes unnecessary WSDL and other sections)
+**Recommended:**
+- "Show me only the 'fields' section from CustomObject.json"
+- "What fields are in the 'fields' section of Profile.json?"
+- "Load the 'description' and 'fields' sections from Flow.json"
+- "Give me just the 'declarative_metadata_sample_definition' from ApexClass.json"
+
+**Avoid:**
+- "Show me the CustomObject metadata type" (too broad - entire file)
+- "Load CustomObject.json" (includes unnecessary WSDL and other sections)
 
 ## JSON File Structure
 
@@ -116,7 +119,7 @@ Some metadata types have additional sections specific to their functionality. Se
 
 ### Section-Specific Loading (BEST PRACTICE)
 
-**⚠️ CRITICAL WARNING: DO NOT use the `read_file` tool (or any whole-file reading tool) on these JSON files!**
+**CRITICAL WARNING: DO NOT use the `read_file` tool (or any whole-file reading tool) on these JSON files!**
 
 `read_file` loads the entire file content into your context, defeating the purpose of section-specific consumption. You will waste 60-80% of your token budget loading unnecessary WSDL segments and verbose sections. (Using `Read` on small files such as this SKILL.md or the index table is fine — this rule is only about the large metadata-type JSON files.)
 
@@ -140,13 +143,13 @@ See [`examples/README.md`](examples/README.md) for complete documentation and us
 
 ### What NOT to Do
 
-**❌ NEVER use the `read_file` tool on these JSON files**:
+**NEVER use the `read_file` tool on these JSON files**:
 ```text
 read_file assets/metadata_api/CustomObject.json  # Loads entire file into context!
 read_file assets/metadata_api/Flow.json          # Wastes 60-80% tokens!
 ```
 
-**❌ NEVER load all files**:
+**NEVER load all files**:
 ```text
 read_file assets/metadata_api/*.json  # This loads ~15MB of data!
 ```

package/skills/platform-metadata-deploy/README.md

@@ -16,7 +16,7 @@ Comprehensive Salesforce DevOps automation using sf CLI v2. Validate, deploy, ve
 
 ### 1. Invoke the skill
 
-```
+```text
 Skill: platform-metadata-deploy
 Request: "Deploy all changes to org dev with validation"
 ```
@@ -61,7 +61,7 @@ After a successful dry run, guide the user to the next safe step:
 
 ## Orchestration Order
 
-```
+```text
 platform-custom-object-generate/automation-flow-generate → platform-metadata-deploy → platform-data-manage
 ```
 

package/skills/platform-metadata-deploy/references/agent-deployment-guide.md

@@ -31,7 +31,7 @@ Agentforce agents consist of multiple metadata components:
 
 ### Metadata Hierarchy
 
-```
+```text
 Bot (Agent Definition)
 └── BotVersion (Version Config)
     └── GenAiPlannerBundle (Reasoning Engine)
@@ -365,7 +365,7 @@ Pass the BotVersion number you intend to activate as the third argument.
 
 **Critical:** Dependencies must be deployed BEFORE the agent.
 
-```
+```text
 1. Custom Objects/Fields (platform-custom-object-generate, platform-custom-field-generate)
    ↓
 2. Apex Classes (platform-apex-generate)