@salesforce/afv-skills 1.13.0 → 1.15.0

package/skills/generating-custom-lightning-type/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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."
+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, Custom Lightning Types (CLTs) with widget/mosaic/fragment rendition/renderer, JSON schemas for agents, type definitions, lightning__objectType, or editor/renderer configurations. When widget renditions are requested, you MUST first read the widget-rendition.md reference file in this skill's references/ directory and follow its complete workflow. This is complex - always use this skill for CLT work."
 metadata:
   version: "1.0"
 ---
@@ -12,6 +12,7 @@ Use this skill when you need to:
 - Generate JSON Schema-based type definitions for Lightning Platform
 - Configure CLTs for Einstein Agent actions
 - Set up editor and renderer configurations for custom UI
+- Create CLTs with widget/mosaic/fragment rendition
 - Troubleshoot deployment errors related to Custom Lightning Types
 
 ## Specification
@@ -28,6 +29,8 @@ Custom Lightning Types (CLTs) are JSON Schema-based type definitions used by the
 - **Include editor/renderer config** only when you need custom UI behavior (custom LWC input/output components). Otherwise, omit.
 
 ## Critical Rules (Read First)
+- **CRITICAL: NEVER include the `"$schema"` field in schema.json**
+  - Salesforce CLT validator WILL REJECT schemas with this field, even if it's a valid JSON Schema `$schema` declaration.
 - **Root object schemas MUST include**:
   - `"type": "object"`
   - `"title"`
@@ -58,45 +61,15 @@ Custom Lightning Types (CLTs) are JSON Schema-based type definitions used by the
 - **Object type validation**: the CLT root is validated to ensure `lightning:type` is exactly `lightning__objectType`.
 
 ## Primitive Types & Constraints
-- `lightning__textType`
-  - Max length 255
-- `lightning__multilineTextType`
-  - Max length 2000
-- `lightning__richTextType`
-  - Max length 100000
-- `lightning__urlType`
-  - Max length 2000
-  - Optional `lightning:allowedUrlSchemes` enum values: `https`, `http`, `relative`, `mailto`, `tel`
-- `lightning__dateType`
-  - Data pattern: YYYY-MM-DD
-- `lightning__timeType`
-  - Data pattern: HH:MM:SS.sssZ
-- `lightning__dateTimeType`
-  - Data shape is an object with required `dateTime` and optional `timeZone`
-- `lightning__numberType`
-  - Decimal numbers; optional `maximum`, `minimum`, `multipleOf`
-- `lightning__integerType`
-  - Whole numbers only; optional `maximum`, `minimum`
-- `lightning__booleanType`
-  - true/false
 
-## Allowed Property-Level Keywords
-When strict validation is enabled (`unevaluatedProperties: false`), keep each property minimal and prefer only keywords known to be allowed:
-- `title`, `description`, `einstein:description`
-- `type` (when used, ensure it matches the chosen `lightning:type`)
-- `lightning:type`
-- `maximum`, `minimum`, `multipleOf` (numeric)
-- `maxLength`, `minLength` (string)
-- `const`, `enum`
-- `lightning:textIndexed`, `lightning:supportsPersonalization`, `lightning:localizable`
-- `lightning:uiOptions`, `lightning:allowedUrlSchemes`
-- `lightning:tags` (metaschema restricts values; currently `flow` is the only known allowed tag)
+When you need the full list of supported primitive `lightning:type` identifiers, their constraints, and the allowed property-level keywords, read `assets/primitive-types-and-constraints.md` in this skill's directory.
 
 ## Generation Workflow
 1. **Confirm the CLT approach**
    - If referencing Apex: capture the exact class reference (`@apexClassType/namespace__ClassName$InnerClass`).
    - If using standard primitives: list the fields, their Lightning primitive types, and which fields are required.
 2. **Draft `schema.json`**
+   - **DO NOT include `"$schema"` at the top**
    - Start with the root object structure (required root fields).
    - Add `properties` using valid primitive `lightning:type` identifiers.
    - For nested-object properties, use **CLT Reference pattern**:
@@ -127,7 +100,7 @@ When strict validation is enabled (`unevaluatedProperties: false`), keep each pr
    - **Avoid known-invalid patterns**:
      - Do not use `es_property_editors/inputList`.
      - Do not use `itemSchema` attributes.
-4. **(Optional) Draft `renderer.json`** (only if custom UI is required)
+4. **(Optional) Draft `renderer.json`** (only if custom UI or mosaic rendition is required)
    - **Supported shape:** Top-level `renderer` object with `renderer.componentOverrides` and `renderer.layout`.
      - Top-level `renderer` object.
      - Use `renderer.componentOverrides` for component overrides.
@@ -138,6 +111,15 @@ When strict validation is enabled (`unevaluatedProperties: false`), keep each pr
      - 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.
+   - **Widget renderer pattern** (for widget rendition):
+       - **When to use:** Use this when users request "mosaic", "widget", "fragment", or "cross-platform rendering" for their CLT.
+       - **Structure:** `renderer.componentOverrides["$"] = { "type": "mosaic", "definition": "tile/mosaic", "children": [ /* UEM tree of blocks and regions */ ] }`
+       - **REQUIRED workflow:**
+           - **STOP**: Do NOT attempt to create the widget renderer yourself.
+           - **MANDATORY FIRST STEP**: You MUST fetch the reference file `references/widget-rendition.md` located in this skill's directory before proceeding.
+           - Follow the complete workflow documented in `widget-rendition.md` using the generated CLT schema as the grounding schema.
+           - The `widget-rendition.md` reference contains the full widget generation workflow: discovering UEM blocks via discoverUiComponents, calling getUiComponentSchemas, building the UEM tree, and writing renderer.json.
+           - **Do not** attempt to generate widget rendition without first fetching the `widget-rendition.md` reference file.
    - **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**:
@@ -166,11 +148,6 @@ When strict validation is enabled (`unevaluatedProperties: false`), keep each pr
          </targets>
      </LightningComponentBundle>
      ```
-7. **Deploy and validate**
-   - Run a final schema sanity check before deploy: valid `lightning:type` names, required fields present, and no disallowed keywords.
-   - 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`).
-
 ## Common Deployment Errors
 | Error / Symptom | Likely Cause | Fix |
 |---|---|---|
@@ -200,3 +177,4 @@ When strict validation is enabled (`unevaluatedProperties: false`), keep each pr
 - [ ] 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
+- [ ] Root schema does NOT include `"$schema"` field

package/skills/generating-custom-lightning-type/assets/primitive-types-and-constraints.md

@@ -0,0 +1,41 @@
+# Primitive Types & Constraints
+
+Reference for all supported Lightning primitive types and their allowed constraints. Read this when authoring property-level `lightning:type` identifiers or determining which keywords are valid on a given property.
+
+## Supported Types
+
+- `lightning__textType`
+  - Max length 255
+- `lightning__multilineTextType`
+  - Max length 2000
+- `lightning__richTextType`
+  - Max length 100000
+- `lightning__urlType`
+  - Max length 2000
+  - Optional `lightning:allowedUrlSchemes` enum values: `https`, `http`, `relative`, `mailto`, `tel`
+- `lightning__dateType`
+  - Data pattern: YYYY-MM-DD
+- `lightning__timeType`
+  - Data pattern: HH:MM:SS.sssZ
+- `lightning__dateTimeType`
+  - Data shape is an object with required `dateTime` and optional `timeZone`
+- `lightning__numberType`
+  - Decimal numbers; optional `maximum`, `minimum`, `multipleOf`
+- `lightning__integerType`
+  - Whole numbers only; optional `maximum`, `minimum`
+- `lightning__booleanType`
+  - true/false
+
+## Allowed Property-Level Keywords
+
+When strict validation is enabled (`unevaluatedProperties: false`), keep each property minimal and prefer only keywords known to be allowed:
+
+- `title`, `description`, `einstein:description`
+- `type` (when used, ensure it matches the chosen `lightning:type`)
+- `lightning:type`
+- `maximum`, `minimum`, `multipleOf` (numeric)
+- `maxLength`, `minLength` (string)
+- `const`, `enum`
+- `lightning:textIndexed`, `lightning:supportsPersonalization`, `lightning:localizable`
+- `lightning:uiOptions`, `lightning:allowedUrlSchemes`
+- `lightning:tags` (metaschema restricts values; currently `flow` is the only known allowed tag)

package/skills/generating-custom-lightning-type/references/widget-rendition.md

@@ -0,0 +1,124 @@
+# Widget Generation Guide
+
+## 📋 Overview
+Widgets are reusable pieces of UI similar to templates, with placeholders for actual data values. The purpose of this file is to assist developers in creating mosaic renditions for CLTs.
+
+## 🎯 Purpose
+Widgets render data in a structured and unified way across various Salesforce experiences like Slack, Mobile, LEX etc.
+
+## Schema Grounding
+Widget generation is **always schema-grounded** using a CLT's schema. The schema describes the data shape the widget should render. Extract property names, types, required vs optional, and nesting from the schema; then follow the full **Workflow** below, using this extracted structure to guide every step. Do not add or remove properties relative to the schema.
+
+## ⚙️ Composition
+A widget is a UEM (Unified Experience Model) tree of blocks and regions. The widget you return must follow the Typescript interfaces below:
+
+```ts
+interface BlockType {
+   type: 'block'
+   definition: string  // {namespace}/{blockName}
+   attributes?: Record<string, any>
+   children?: (BlockType | RegionType)[]
+}
+
+interface RegionType {
+   type: 'region'
+   name: string
+   children: BlockType[]
+}
+```
+---
+
+## 🔧 Available Metadata Actions
+
+### When to Use Each Action
+
+#### discoverUiComponents
+
+**Purpose:** Discover the palette of available blocks that can be used in widget composition.
+
+**Use for:** Finding available blocks before building your widget structure.
+
+**Input Parameters:**
+- `actionName` (**required***): "discoverUiComponents"
+- `metadataType` (**required**): "FRAGMENT"
+- `parameters` (**required**): JSON object with the below fields
+  - `pageType` (**required**): "FRAGMENT"
+  - `pageContext` (optional): JSON object - not required for FRAGMENT type
+  - `searchQuery` (optional): String to filter components by name or description
+
+**Returns:** List of components with:
+- `definition`: Fully qualified name (e.g., "namespace/definiton")
+- `description`: Component description
+- `label`: Human-readable label
+- `attributes`: Optional attribute metadata
+
+#### getUiComponentSchemas
+
+**Purpose:** Get detailed JSON schemas for component configuration, including property types, required vs optional fields, and validation rules.
+
+**Use for:** You know which components you want but need to understand their properties before adding them to your widget.
+
+**Input Parameters:**
+- `actionName` (**required***): "getUiComponentSchemas"
+- `metadataType` (**required**): "FRAGMENT"
+- `parameters` (**required**): JSON object with the below fields
+  - `pageType` (**required**): "FRAGMENT"
+  - `componentDefinitions` (**required**): List of fully qualified names (e.g., ["namespace/definition"])
+    - **CRITICAL**: NEVER include "tile/mosaic" in this list. "tile/mosaic" is a container component used in renderer.json structure and **should not** be passed to getUiComponentSchemas
+  - `pageContext` (optional): JSON object - not required for FRAGMENT type
+  - `includeKnowledge` (optional): Boolean, defaults to true - includes additional component-specific guidance
+
+**Returns:**
+- `componentSchemas`: List of results (supports partial failures)
+- **Success entries**: Contains JSON schema with property definitions, types, constraints
+- **Failure entries**: Contains error message explaining why schema couldn't be retrieved
+- `$defs`: Schema definitions and references (if schema transformation applied)
+
+**Key Feature:** Supports partial failures - if some components can't be found, you still get schemas for the successful ones.
+
+---
+
+## Attribute binding using placeholder syntax
+
+- **Where to use:** When block properties must display or pass runtime data from the grounding schema, use the **Placeholder Syntax** below so that the runtime binds values into the widget. Check each block's schema (from `getUiComponentSchemas`) for the correct property name (e.g. `value`, `text`, `label`).
+- **Placeholder Syntax:** Use `{!$attrs.<attrName>}` as the placeholder for each block property that should receive data.
+  `<attrName>` **must** match the property name from the grounding schema so that the runtime can resolve its value.
+  Example: for a schema property `title`, set the block property to `{!$attrs.title}`.
+- **List / iterative data:** Only the children (list items) hold bound values; the parent list block does not. For each item inside a list (e.g. `tile/listItem`), use `{!$attrs.<listAttrName>.item}` so the runtime binds the current item. `<listAttrName>` MUST match the schema property name of the list. Example: for `icons`, use `"{!$attrs.icons.item}"` on the list item.
+
+---
+
+## 💡Workflow
+
+1. **Schema Parsing**
+- Parse the schema and extract: property names, types, required vs optional, and nested structure. Use this as the **widget spec**.
+
+2. **Discover Available Blocks** (**REQUIRED** - do NOT skip)
+- Use **discoverUiComponents metadata action** above to explore what blocks are available.
+- Use property types from the **widget spec** to inform `searchQuery` (e.g. text → "text", number → "number").
+
+3. **Select Components**
+- Choose blocks that can represent each property in the **widget spec** from the results of step 2.
+
+4. **Get Component Schemas** (**REQUIRED** - do NOT skip)
+- Use **getUiComponentSchemas metadata action** with the selected block definitions from step 3 and review block properties' metadata.
+
+5. **Build Widget**
+- Construct the UEM tree. Map each property in the **widget spec** to block properties and preserve order of the **widget spec**.
+- For block properties that must show or pass runtime data, use the placeholder syntax (see **Attribute binding using placeholder syntax** above).
+- Use block properties from the schemas retrieved in step 4.
+
+6. **Write output to CLT Bundle**
+- Always write to `lightningTypes/<TypeName>/lightningDesktopGenAi/renderer.json` (or the correct target subfolder for the product surface, e.g. `experienceBuilder/`, `lightningMobileGenAi/`, `enhancedWebChat/` when applicable).
+  Check **required root override pattern** below -
+  `renderer.componentOverrides["$"] = { "type": "mosaic", "definition": "tile/mosaic", "children": [ ... ] — array of UEM nodes - contains the widget UEM generated using the **Workflow** steps 1-5 above }`
+
+---
+
+## ⚠️ Important Notes
+
+- **widget spec** includes both required and optional attributes - review carefully to ensure valid configuration.
+- When using **`execute_metadata_action`** tool, always supply **`parameters`** with the required fields above; missing `parameters` or required keys causes hard failures, not partial results.
+- Block definitions always follow the `{namespace}/{blockName}` convention.
+- Use the same definition format returned by `discoverUiComponents` when calling `getUiComponentSchemas`
+- Placeholder syntax for non-list properties is `{!$attrs.<attrName>}` and for list properties is `{!$attrs.<listAttrName>.item}`.

package/skills/generating-ui-bundle-custom-app/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: generating-ui-bundle-custom-app
+description: "MUST activate when the project contains a uiBundles/*/src/ directory and the task involves creating or configuring a Custom Application for hosting a UI bundle in Lightning Experience. Use this skill when creating a CustomApplication metadata record to surface the UI bundle in the App Launcher. Activate when files matching applications/*.app-meta.xml exist and need modification, or when the user wants to expose their app via the Lightning App Launcher without a Digital Experience Site. Do NOT use generating-custom-application for this — UI bundle apps do not use tabs, action overrides, or flexipages."
+metadata:
+  version: "1.0"
+---
+
+# Custom Application for React UI Bundles
+Create and configure a Salesforce Custom Application that hosts a React UI bundle in Lightning Experience. This skill generates the CustomApplication metadata so the app appears in the Lightning App Launcher and can be accessed by internal users.
+
+Custom Applications differ from Experience Sites: they don't need Networks, CustomSite, DigitalExperienceConfig, or DigitalExperienceBundle metadata. The Custom Application acts as a thin launcher entry that delegates rendering to the React UI bundle referenced by `uiBundle`.
+
+## Required Properties
+Resolve all properties before generating any metadata. Each has a fallback chain — work through each option in order until a value is found.
+
+| Property | Format | How to Resolve |
+|----------|--------|----------------|
+| **appName** | `lowercamelcase` (e.g., `myInternalApp`) | The UI bundle name from `uiBundles/<name>/` directory |
+| **appNamespace** | String | `namespace` in `sfdx-project.json` → `sf data query -q "SELECT NamespacePrefix FROM Organization" --target-org ${usernameOrAlias}` → default `c` |
+| **appLabel** | Human-readable string | User-provided, or derive from appName by converting camelCase to Title Case |
+
+The `appNamespace` and `appName` connect the Custom Application to the correct React UI bundle. In newer API versions this uses `<uiBundle>{appNamespace}__{appName}</uiBundle>`; in older versions it uses `<webApplication>{appName}</webApplication>`. Getting this wrong means the app launcher entry exists but shows a blank page. Step 2 of the workflow determines which field to use.
+
+## Generation Workflow
+### Step 1: Resolve All Required Properties
+Determine values for all properties before constructing anything. Use the resolution strategies in the table above.
+
+### Step 2: Query API Context (Version-Aware Field Discovery)
+Call `salesforce-api-context` MCP tools to discover which fields exist for the target org's API version. This ensures the generated metadata is compatible with the user's Salesforce version.
+
+**Required calls:**
+1. Call `get_metadata_type_fields` for `CustomApplication` — check whether the `uiBundle` field exists
+2. Call `get_metadata_type_fields` for `UIBundle` — check whether the `target` field exists
+
+**Field resolution based on API response:**
+
+| Field Check | If present | If absent (older API version) |
+|-------------|-----------|-------------------------------|
+| `CustomApplication.uiBundle` | Use `<uiBundle>{appNamespace}__{appName}</uiBundle>` | Use `<webApplication>{appName}</webApplication>` (no namespace) |
+| `UIBundle.target` | Use `<target>CustomApplication</target>` | Omit the `<target>` element entirely |
+
+If `salesforce-api-context` is unavailable after a real attempt, fall back to the newer field names (`uiBundle` + `target`).
+
+### Step 3: Create the Project Structure
+Create any files and directories that don't already exist:
+
+| Metadata Type | Path |
+|--------------|------|
+| CustomApplication | `<sourceDir>/applications/{appName}.app-meta.xml` |
+
+**Note:** `<sourceDir>` is determined from `sfdx-project.json`. Read `packageDirectories[]` and use the entry where `"default": true`; the full source directory is `<path>/main/default`. If no default is set, use the first entry. Commonly `force-app/main/default`, but this path is configurable.
+
+### Step 4: Populate All Metadata Fields
+Use the default template in the doc below. Values in `{braces}` are resolved property references — substitute them with the actual values from Step 1. Apply the field resolution from Step 2 to determine which XML elements to use.
+
+| Metadata Type | Template Reference |
+|--------------|-------------------|
+| CustomApplication | [configure-metadata-custom-application.md](docs/configure-metadata-custom-application.md) |
+
+### Execution Note for Step 4: Load and use the doc
+- Agents MUST read the full contents of the docs/*.md file referenced in Step 4 before attempting to populate metadata fields.
+- Read the file in full, replace placeholders (e.g. `{appName}`) with the resolved values, then use the expanded template to populate the metadata XML content.
+- If Step 2 determined the older field names apply, substitute `<uiBundle>` with `<webApplication>` in the generated output.
+
+### Step 5: Update UI Bundle Meta XML
+If Step 2 confirmed the `target` field exists on `UIBundle`, add `<target>CustomApplication</target>` to the `.uibundle-meta.xml` file (skip if the field doesn't exist in the org's API version):
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<UIBundle xmlns="http://soap.sforce.com/2006/04/metadata">
+    <masterLabel>{appName}</masterLabel>
+    <description>A Salesforce UI Bundle.</description>
+    <isActive>true</isActive>
+    <version>1</version>
+    <target>CustomApplication</target>
+</UIBundle>
+```
+
+### Step 6: Do Not Modify Non-Templated Properties
+Do not modify any default property values for `CustomApplication` metadata that are not expressed as variables wrapped in `{braces}`.
+
+## Verification Checklist
+Before deploying, confirm:
+
+- [ ] All required properties are resolved
+- [ ] API context was queried to determine available fields (Step 2)
+- [ ] `applications/{appName}.app-meta.xml` exists with correct content
+- [ ] The bundle reference field matches the org's API version (`<uiBundle>` or `<webApplication>`)
+- [ ] If `target` field is supported: `.uibundle-meta.xml` has `<target>CustomApplication</target>`
+- [ ] Deployment validates successfully:
+```bash
+sf project deploy validate --metadata CustomApplication UIBundle --target-org ${usernameOrAlias}
+```

package/skills/generating-ui-bundle-custom-app/docs/configure-metadata-custom-application.md

@@ -0,0 +1,70 @@
+# Configure Metadata: CustomApplication
+
+## Purpose
+This configuration file creates a **net-new, default** CustomApplication metadata record for a Lightning Experience app that hosts a React UI bundle. It is not intended to edit or modify an existing CustomApplication record. Use this template only when provisioning a brand-new Custom Application for a UI bundle.
+
+## File Location
+```
+<sourceDir>/applications/{appName}.app-meta.xml
+```
+
+**Note:** Determine `<sourceDir>` from `sfdx-project.json` → `packageDirectories[]` → find the entry with `"default": true` → use its `path` value + `/main/default`. Commonly `force-app/main/default`, but this is configurable.
+
+## Default Template (newer API versions — `uiBundle` field available)
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<CustomApplication xmlns="http://soap.sforce.com/2006/04/metadata">
+    <brand>
+        <headerColor>#0070D2</headerColor>
+        <shouldOverrideOrgTheme>false</shouldOverrideOrgTheme>
+    </brand>
+    <formFactors>Small</formFactors>
+    <formFactors>Large</formFactors>
+    <isNavAutoTempTabsDisabled>false</isNavAutoTempTabsDisabled>
+    <isNavPersonalizationDisabled>false</isNavPersonalizationDisabled>
+    <isNavTabPersistenceDisabled>false</isNavTabPersistenceDisabled>
+    <isOmniPinnedViewEnabled>false</isOmniPinnedViewEnabled>
+    <label>{appLabel}</label>
+    <navType>Standard</navType>
+    <uiBundle>{appNamespace}__{appName}</uiBundle>
+    <uiType>Lightning</uiType>
+</CustomApplication>
+```
+
+## Fallback Template (older API versions — `uiBundle` field NOT available)
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<CustomApplication xmlns="http://soap.sforce.com/2006/04/metadata">
+    <brand>
+        <headerColor>#0070D2</headerColor>
+        <shouldOverrideOrgTheme>false</shouldOverrideOrgTheme>
+    </brand>
+    <formFactors>Small</formFactors>
+    <formFactors>Large</formFactors>
+    <isNavAutoTempTabsDisabled>false</isNavAutoTempTabsDisabled>
+    <isNavPersonalizationDisabled>false</isNavPersonalizationDisabled>
+    <isNavTabPersistenceDisabled>false</isNavTabPersistenceDisabled>
+    <isOmniPinnedViewEnabled>false</isOmniPinnedViewEnabled>
+    <label>{appLabel}</label>
+    <navType>Standard</navType>
+    <webApplication>{appName}</webApplication>
+    <uiType>Lightning</uiType>
+</CustomApplication>
+```
+
+## Field Reference
+
+| Field | Required | Version | Description |
+|-------|----------|---------|-------------|
+| `brand.headerColor` | Yes | All | Hex color for the app header bar in Lightning Experience. Default: `#0070D2` (Salesforce blue). |
+| `brand.shouldOverrideOrgTheme` | Yes | All | Whether this app's branding overrides the org theme. Default: `false`. |
+| `formFactors` | Yes | All | Supported form factors. Include both `Small` (mobile) and `Large` (desktop) for full coverage. |
+| `isNavAutoTempTabsDisabled` | Yes | All | Disable auto-creation of temporary tabs. Default: `false`. |
+| `isNavPersonalizationDisabled` | Yes | All | Disable user personalization of navigation. Default: `false`. |
+| `isNavTabPersistenceDisabled` | Yes | All | Disable persistence of nav tabs across sessions. Default: `false`. |
+| `isOmniPinnedViewEnabled` | Yes | All | Enable Omni-channel pinned view. Default: `false`. |
+| `label` | Yes | All | Human-readable label shown in the App Launcher and app switcher. |
+| `navType` | Yes | All | Navigation type. Use `Standard` for standard Lightning navigation. |
+| `uiBundle` | Conditional | Newer | Namespace-qualified developer name of the UI bundle (`{appNamespace}__{appName}`). Use when `get_metadata_type_fields` confirms this field exists on `CustomApplication`. |
+| `webApplication` | Conditional | Older | Developer name of the UI bundle (`{appName}`, no namespace). Use when `uiBundle` field is not available. |
+| `uiType` | Yes | All | UI framework type. Must be `Lightning` for UI bundle apps. |

package/skills/generating-ui-bundle-metadata/SKILL.md

@@ -24,6 +24,7 @@ After generation:
 1. Replace all default boilerplate — "React App", "Vite + React", default `<title>`, placeholder text
 2. Populate the home page with real content (landing section, banners, hero, navigation)
 3. Update navigation and placeholders (see the `building-ui-bundle-frontend` skill)
+4. **Configure a hosting target** — a UI bundle without a `<target>` in its meta XML will not be visible in the org. Use `generating-ui-bundle-custom-app` for internal (App Launcher) apps or `generating-ui-bundle-site` for external (Experience Site) apps.
 
 Always install dependencies before running any scripts in the UI bundle directory.
 
@@ -39,7 +40,44 @@ A UIBundle bundle lives under `uiBundles/<AppName>/` and must contain:
 ### Meta XML
 
 Required fields: `masterLabel`, `version` (max 20 chars), `isActive` (boolean).
-Optional: `description` (max 255 chars).
+Optional: `description` (max 255 chars), `target`.
+
+#### Target Field
+
+The `<target>` element specifies where the UI bundle is hosted:
+
+| Value | Use Case | Companion Metadata |
+|-------|----------|-------------------|
+| `Experience` | External-facing site via Digital Experience | Network, CustomSite, DigitalExperienceConfig, DigitalExperienceBundle |
+| `CustomApplication` | Internal app via Lightning App Launcher | CustomApplication (`applications/*.app-meta.xml`) |
+
+A `<target>` is **required** for the app to be accessible in a Salesforce org. A UI bundle deployed without a target will not appear anywhere — no App Launcher entry, no Experience Site URL. Always pair the bundle with one of:
+- `generating-ui-bundle-site` (for `Experience` target)
+- `generating-ui-bundle-custom-app` (for `CustomApplication` target)
+
+**Example with Experience target:**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<UIBundle xmlns="http://soap.sforce.com/2006/04/metadata">
+    <masterLabel>propertyrentalapp</masterLabel>
+    <description>A Salesforce UI Bundle.</description>
+    <isActive>true</isActive>
+    <version>1</version>
+    <target>Experience</target>
+</UIBundle>
+```
+
+**Example with CustomApplication target:**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<UIBundle xmlns="http://soap.sforce.com/2006/04/metadata">
+    <masterLabel>propertymanagementapp</masterLabel>
+    <description>A Salesforce UI Bundle.</description>
+    <isActive>true</isActive>
+    <version>1</version>
+    <target>CustomApplication</target>
+</UIBundle>
+```
 
 ### ui-bundle.json
 

package/skills/investigating-agentforce-architecture/README.md

@@ -0,0 +1,156 @@
+# investigating-agentforce-architecture
+
+Declared architecture snapshot for a single Agentforce agent: planner + topics + actions + flows + Apex + prompts + NGA plugins. Reads design-time metadata only (`BotDefinition` + `GenAi*` Tooling objects + Metadata API retrieve) — no runtime audit data.
+
+Input: an `agent_api_name` (the `BotDefinition.DeveloperName`) and an org alias. Optional `agent_version_api_name` to pin a version; otherwise the active `BotVersion` resolves.
+
+Output: two files under `~/.vibe/data/investigating-agentforce-architecture/<org_id15>/<agent>__<version>/` — a normalized `<agent>_<ver>_metadata_tree.json` and a human-readable `<agent>_<ver>_architecture.md`. Override with `--data-dir <path>` (other runtimes pass this to land artifacts under their own distribution layout).
+
+---
+
+## Runtime budget
+
+**30–45s typical, ≤60s hard cap** on the reference fixtures.
+
+A naive sequential implementation (Metadata API retrieves only) would take 90–220s. Speedup: **3–5×**.
+
+Scaling note: large bots with many flows scale approximately linearly in flow count. Each Flow metadata retrieve is an individual SOQL round-trip; a 20-flow bot takes proportionally longer than a 5-flow bot. The 7 planner-side Tooling SOQL fan-outs are constant-cost (single fan-out regardless of bot size); the flow/apex body fetch wave scales with ref count.
+
+---
+
+## Prerequisites
+
+| Tool | Why |
+|---|---|
+| `sf` CLI (authenticated against the target org) | Shells `sf org display --target-org <alias> --json` for access token, and `sf sobject describe` for the 7-day channel probe |
+| Python 3.10+ | `pathlib`, dataclasses, `\|` union types, `concurrent.futures` |
+
+---
+
+## Usage
+
+Invoked conversationally through whatever skill-aware runtime hosts it. Example prompts:
+
+| User says | Skill does |
+|---|---|
+| `document the architecture of MyAgent in my-org-alias` | Resolve active version, fetch tree, render architecture.md + Mermaid |
+| `draw the invocation graph for MySalesAgent v5 in my-org-alias-3` | Same, pinned to v5 |
+| `what tools does MyAgent2 have in my-org-alias-2` | Fetch tree, surface the plugin/function inventory from the rendered architecture.md |
+| `re-fetch the architecture of MyAgent — I think metadata changed` | Pass `--force` to bypass the cache |
+
+See `SKILL.md` for the full flag table and sample prompts.
+
+---
+
+## Directory layout
+
+```
+investigating-agentforce-architecture/
+├── SKILL.md                       Skill contract (inputs, outputs, pipeline, invariants)
+├── README.md                      This file
+├── assets/
+│   ├── soql/*.soql                Tooling + Data SOQL templates
+│   ├── cli/*.yaml                 sf CLI recipes (subprocess invocation specs)
+│   └── mermaid/*.mmd              Mermaid templates for the invocation graph
+├── references/
+│   ├── soql_fields.md             Per-sObject field reference (13 sObjects)
+│   ├── architecture_sections.md   Section-by-section structure of the rendered architecture.md
+│   └── contract.json              metadata_tree.json schema contract
+├── scripts/
+│   ├── _shared/                   Path helpers + fs_guard validators + sql escapers
+│   ├── main.py                    Orchestrator entry point
+│   ├── config.py                  Shared paths, cache TTLs, validated path builders
+│   ├── soql_loader.py             Template loader with fs_guard-validated substitution
+│   ├── sf_cli.py                  sf CLI subprocess wrapper (yaml.safe_load + stderr redaction)
+│   ├── rest_client.py             urllib wrapper (Authorization-stripping redirect handler)
+│   ├── resolve_bot.py             BotDefinition + BotVersion + planner name lookup
+│   ├── retrieve_planner.py        Metadata retrieve for GenAiPlannerBundle + NGA plugins
+│   ├── parallel_retrieve.py       7-channel parallel Tooling SOQL fan-out
+│   ├── parse_bundle.py            XML → normalized node shapes
+│   ├── parse_wave.py              BFS expansion of flow/apex/prompt refs
+│   ├── probe_channels.py          7-day-TTL channel describe probe
+│   ├── cache_check.py             Asset-hash-aware cache freshness
+│   ├── finalize.py                Merge waves → metadata_tree.json
+│   ├── render_architecture.py     architecture.md + Mermaid graph
+│   ├── resolve_invocation_target.py  ID-prefix router for NGA InvocationTargets
+│   └── tests/                     Unit + integration tests (unittest)
+└── tools/
+    ├── emit_env.py                Env-var emit helper (Phase 0.5)
+    ├── emit_result.py             Final RESULT block renderer
+    ├── sanitize.py                Stdin → safe-string filter
+    └── write_emit_ctx.py          Per-phase ctx writer
+```
+
+---
+
+## Architecture
+
+### Channel strategy — SOQL-first
+
+```
+Seed query: planner_definition_by_agent_chain (chain-LIKE lookup → planner id)
+
+6 parallel Tooling SOQL channels (keyed on the resolved planner id):
+    - plugins_by_planner
+    - planner_bundle_functions (join)
+    - functions_by_plugins
+    - planner_attrs_by_parent_ids
+    - plugin_functions_by_plugin_ids (join)
+    - plugin_instructions_by_plugin_ids
+
++ Data API SOQL for Flow / Apex bodies (batched by id list)
++ Metadata retrieve ONLY for:
+    - GenAiPromptTemplate (prompt bodies)
+    - NGA external plugins (when planner is ConcurrentMultiAgentOrchestration etc.)
+```
+
+Most of the 3–5× speedup over a naive Metadata-API-only implementation comes from collapsing a sequential zip-retrieve chain into a single Tooling SOQL fan-out.
+
+### Planner normalization — classic ReAct vs NGA
+
+One tree shape, two planner families:
+
+| `PlannerType` examples | Family | InvocationTarget style |
+|---|---|---|
+| `ReactAiPlannerV1`, `SequentialPlannerIntentClassifier` | Classic ReAct | DeveloperName strings |
+| `ConcurrentMultiAgentOrchestration`, `AnthropicCompatibleV1` | NGA | Sometimes 15/18-char Ids (ID-prefix routed) |
+
+`resolve_invocation_target.py` routes NGA InvocationTargets by Salesforce ID prefix (`01p` → ApexClass, `301` → Flow, etc.). Unknown prefixes become `_unresolved[]` entries with `reason="unknown-id-prefix:<prefix>"` — never silently dropped.
+
+### Cache layers
+
+1. **Tree cache** — `metadata_tree.json` is reused unless `--force`. Cache key includes asset-hashes of every SOQL / YAML / Mermaid template shipped with the skill, so changing a template busts the cache automatically.
+2. **Channel probe cache** — 7-day TTL on `sf sobject describe` results for the 13 sObjects the skill touches. `--reprobe` forces a refresh (needed after Salesforce quarterly releases that rename / remove fields). Mandatory-field gate: a probe that sees any mandatory field missing (per `probe_channels.MANDATORY_FIELDS`) flips `status: PROBE_FAILED` so the caller surfaces a clean error.
+
+---
+
+## Key behaviors
+
+### Idempotence
+
+Re-running the same `(org, agent, version)` overwrites prior artifacts in place. Safe to run repeatedly during development.
+
+### Partial-results surfacing
+
+No silent drops. Any unresolved ref — unknown ID prefix, failed SOQL, missing describe field — lands in `_unresolved[]` with a `reason=...` string. Top-level `STATUS` is `OK` on a clean run, `PARTIAL_OK` when any channel degrades.
+
+### Cycle handling
+
+Per-branch ancestor-path cycle detection is the primary termination primitive: the same flow visited along its own ancestor chain emits `_cycle_back_to:<path>` instead of recursing. `MAX_BFS_DEPTH=20` is a defensive last-resort guard against pathological graphs that evade per-branch detection; real-world agents bottom out well before that.
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `sf org display failed` | Re-authenticate: `sf org login web --alias <alias>` |
+| `INVALID_FIELD` from a SOQL asset | Salesforce renamed / removed the field in a quarterly release. Run with `--reprobe` to refresh the 7-day channel cache and pick up the new schema |
+| `STATUS=PROBE_FAILED` on first run | Channel probe saw a mandatory field missing. Check `channels.json` under the probe cache dir for which sObject / field — may require org-side feature enablement |
+| Tree for classic ReAct agent shows `_unresolved` entries for NGA plugins | Expected — the NGA external-plugin retrieve is skipped when the planner shape is classic. Those entries can be ignored |
+
+---
+
+## Author
+
+Raghul Jayagopal (RJ), Salesforce ANZ FDE.