@salesforce/afv-skills 1.21.0 → 1.23.0

package/skills/external-diagram-visual-generate/scripts/check-prerequisites.sh

@@ -0,0 +1,101 @@
+#!/bin/bash
+# check-prerequisites.sh - Verify external-diagram-visual-generate requirements before use
+# Returns 0 if all required checks pass, 1 if any required fail
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+GRAY='\033[0;90m'
+NC='\033[0m'
+
+ERRORS=0
+WARNINGS=0
+
+echo ""
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo -e "${BLUE}  📸 SF-IMAGEN PREREQUISITES CHECK${NC}"
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo ""
+echo -e "${GRAY}  REQUIRED:${NC}"
+
+# Check 1: macOS (required for Preview app)
+echo -n "  Checking macOS (for Preview app)... "
+if [[ "$OSTYPE" == "darwin"* ]]; then
+    echo -e "${GREEN}✓ macOS detected${NC}"
+else
+    echo -e "${RED}✗ Not macOS${NC}"
+    echo -e "    ${YELLOW}→ external-diagram-visual-generate uses macOS Preview app for image display${NC}"
+    echo -e "    ${YELLOW}→ Current OS: $OSTYPE${NC}"
+    ERRORS=$((ERRORS + 1))
+fi
+
+# Check 2: Gemini API Key
+echo -n "  Checking GEMINI_API_KEY... "
+if [[ -n "$GEMINI_API_KEY" ]]; then
+    # Mask the key for display
+    MASKED_KEY="${GEMINI_API_KEY:0:10}...${GEMINI_API_KEY: -4}"
+    echo -e "${GREEN}✓ Set ($MASKED_KEY)${NC}"
+else
+    echo -e "${RED}✗ Not set${NC}"
+    echo -e "    ${YELLOW}→ Nano Banana Pro requires a personal API key${NC}"
+    echo -e "    ${YELLOW}→ Get one at: https://aistudio.google.com/apikey${NC}"
+    echo -e "    ${YELLOW}→ Add to ~/.zshrc: export GEMINI_API_KEY=\"your-key\"${NC}"
+    ERRORS=$((ERRORS + 1))
+fi
+
+# Check 3: Gemini CLI
+echo -n "  Checking Gemini CLI... "
+if command -v gemini &> /dev/null; then
+    GEMINI_VERSION=$(gemini --version 2>/dev/null | head -1 || echo "installed")
+    echo -e "${GREEN}✓ $GEMINI_VERSION${NC}"
+else
+    echo -e "${RED}✗ Not installed${NC}"
+    echo -e "    ${YELLOW}→ Install: npm install -g @google/gemini-cli${NC}"
+    ERRORS=$((ERRORS + 1))
+fi
+
+# Check 4: Nano Banana Extension
+echo -n "  Checking Nano Banana extension... "
+if gemini extensions list 2>/dev/null | grep -q "nanobanana"; then
+    echo -e "${GREEN}✓ Installed${NC}"
+else
+    echo -e "${RED}✗ Not installed${NC}"
+    echo -e "    ${YELLOW}→ Install: gemini extensions install nanobanana${NC}"
+    ERRORS=$((ERRORS + 1))
+fi
+
+echo ""
+echo -e "${GRAY}  OPTIONAL (for 4K/editing via Python script):${NC}"
+
+# Check 5: uv (optional, for Python script)
+echo -n "  Checking uv (Python runner)... "
+if command -v uv &> /dev/null; then
+    UV_VERSION=$(uv --version 2>&1 | head -1)
+    echo -e "${GREEN}✓ $UV_VERSION${NC}"
+else
+    echo -e "${YELLOW}○ Not installed (optional)${NC}"
+    echo -e "    ${GRAY}→ For 4K resolution/editing: curl -LsSf https://astral.sh/uv/install.sh | sh${NC}"
+    WARNINGS=$((WARNINGS + 1))
+fi
+
+echo ""
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+
+if [[ $ERRORS -eq 0 ]]; then
+    if [[ $WARNINGS -gt 0 ]]; then
+        echo -e "  ${GREEN}✅ All required prerequisites met!${NC}"
+        echo -e "  ${YELLOW}⚠️  $WARNINGS optional feature(s) unavailable${NC}"
+    else
+        echo -e "  ${GREEN}✅ All prerequisites met! external-diagram-visual-generate is ready to use.${NC}"
+    fi
+    echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+    echo ""
+    exit 0
+else
+    echo -e "  ${RED}❌ $ERRORS required prerequisite(s) missing.${NC}"
+    echo -e "  ${RED}   Please fix before using external-diagram-visual-generate.${NC}"
+    echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+    echo ""
+    exit 1
+fi

package/skills/integration-connectivity-connected-app-configure/README.md

@@ -0,0 +1,99 @@
+# integration-connectivity-connected-app-configure
+
+Salesforce Connected Apps & External Client Apps skill for Claude Code.
+
+## Overview
+
+This skill helps you create and manage:
+
+- **Connected Apps**: Traditional OAuth-enabled applications for Salesforce integration
+- **External Client Apps (ECAs)**: Modern, security-first applications with enhanced controls (API 61.0+)
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| App Generation | Create Connected Apps or ECAs from requirements |
+| Security Scoring | 120-point validation across 6 categories |
+| Template Library | Pre-built templates for common OAuth flows |
+| Migration Support | Guidance for Connected App → ECA migration |
+| Best Practices | Built-in security recommendations |
+
+## Quick Start
+
+### Create a Connected App
+
+```
+Use the integration-connectivity-connected-app-configure skill to create a Connected App named "MyIntegration"
+with API and RefreshToken scopes for server-to-server integration.
+```
+
+### Create an External Client App
+
+```
+Use the integration-connectivity-connected-app-configure skill to create an External Client App named
+"MobileApp" for a mobile application with PKCE enabled.
+```
+
+### Review Existing Apps
+
+```
+Use the integration-connectivity-connected-app-configure skill to review and score my existing Connected Apps
+for security best practices.
+```
+
+## Scoring Categories
+
+| Category | Points | Focus |
+|----------|--------|-------|
+| Security | 30 | PKCE, rotation, certificates |
+| OAuth Configuration | 25 | Callbacks, flows, tokens |
+| Metadata Compliance | 20 | Required fields, API version |
+| Best Practices | 20 | Minimal scopes, admin approval |
+| Scopes | 15 | Least privilege principle |
+| Documentation | 10 | Description, contact info |
+
+## When to Use Each App Type
+
+### Choose Connected App When:
+- Simple, single-org integration
+- Legacy system compatibility needed
+- Quick setup is priority
+- No cross-org deployment needs
+
+### Choose External Client App When:
+- Multi-org or ISV distribution
+- Automated secret rotation required
+- Enhanced audit logging needed
+- Full metadata compliance required
+- Packaging in 2GP
+
+## Directory Structure
+
+```
+integration-connectivity-connected-app-configure/
+├── skills/
+│   └── integration-connectivity-connected-app-configure/
+│       └── SKILL.md          # Main skill definition
+├── assets/
+│   ├── connected-app-basic.xml
+│   ├── connected-app-oauth.xml
+│   ├── connected-app-jwt.xml
+│   ├── connected-app-canvas.xml
+│   ├── external-client-app.xml
+│   ├── eca-global-oauth.xml
+│   ├── eca-oauth-settings.xml
+│   └── eca-policies.xml
+├── references/
+│   └── example-usage.md
+├── references/
+│   ├── oauth-flows-reference.md
+│   ├── security-checklist.md
+│   └── migration-guide.md
+└── README.md
+```
+
+## Dependencies
+
+- **platform-metadata-deploy**: For deploying apps to orgs
+- **sf-metadata**: For creating related metadata (Named Credentials)

package/skills/integration-connectivity-connected-app-configure/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: integration-connectivity-connected-app-configure
+description: "Salesforce Connected Apps and External Client Apps OAuth configuration with 120-point scoring. Use this skill to configure OAuth flows, JWT bearer auth, Connected Apps, and External Client Apps in Salesforce. TRIGGER when: user configures OAuth flows, JWT bearer auth, Connected Apps, ECAs, or touches .connectedApp-meta.xml / .eca-meta.xml files. DO NOT TRIGGER when: configuring Named Credentials for callouts (use integration-connectivity-generate), reviewing permission policies (use platform-metadata-deploy), or writing Apex token-handling code (use platform-apex-generate)."
+allowed-tools: Bash Read Write Edit Glob Grep WebFetch AskUserQuestion TodoWrite
+metadata:
+  version: "1.1"
+---
+
+# integration-connectivity-connected-app-configure: Salesforce Connected Apps & External Client Apps
+
+Use this skill when the user needs **OAuth app configuration** in Salesforce: Connected Apps, External Client Apps (ECAs), JWT bearer setup, PKCE decisions, scope design, or migration from older Connected App patterns to newer ECA patterns.
+
+## Scope
+
+**In scope:**
+- `.connectedApp-meta.xml` or `.eca-meta.xml` files
+- OAuth flow selection and callback / scope setup
+- JWT bearer auth, device flow, client credentials, or auth-code decisions
+- Connected App vs External Client App architecture choices
+- Consumer key / secret / certificate handling strategy
+
+**Out of scope — delegate elsewhere:**
+- Configuring Named Credentials or runtime callouts → [integration-connectivity-generate](../integration-connectivity-generate/SKILL.md)
+- Deploying metadata to orgs → [platform-metadata-deploy](../platform-metadata-deploy/SKILL.md)
+- Writing Apex token-handling code → [platform-apex-generate](../platform-apex-generate/SKILL.md)
+
+---
+
+## First Decision: Connected App or External Client App
+
+| If the need is... | Prefer |
+|---|---|
+| simple single-org OAuth app | Connected App |
+| new development with better secret handling | External Client App |
+| multi-org / packaging / stronger operational controls | External Client App |
+| straightforward legacy compatibility | Connected App |
+
+Default guidance:
+- Choose **ECA** for new regulated, packageable, or automation-heavy solutions.
+- Choose **Connected App** when simplicity and legacy compatibility matter more.
+- Spring '26 note: creation of new Connected Apps is disabled by default in orgs. For new integrations, prefer External Client Apps unless Connected App compatibility is explicitly required.
+
+---
+
+## Required Inputs
+
+Ask for or infer:
+- App type: Connected App or ECA
+- OAuth flow: auth code, PKCE, JWT bearer, device, client credentials
+- Client type: confidential vs public
+- Callback URLs / redirect surfaces
+- Required scopes
+- Distribution model: local org only vs packageable / multi-org
+- Whether certificates or secret rotation are required
+
+---
+
+## Workflow
+
+### 1. Choose the app model
+Decide whether a Connected App or ECA is the better long-term fit using the decision table above.
+
+### 2. Choose the OAuth flow
+
+| Use case | Default flow |
+|---|---|
+| backend web app | Authorization Code |
+| SPA / mobile / public client | Authorization Code + PKCE |
+| server-to-server / CI/CD | JWT Bearer |
+| device / CLI auth | Device Flow |
+| service account style app | Client Credentials (typically ECA) |
+
+### 3. Start from the right template
+Read the appropriate template before generating — do not build from scratch:
+
+| Template | Use case |
+|---|---|
+| `assets/connected-app-basic.xml` | Simple API integration, minimal OAuth |
+| `assets/connected-app-oauth.xml` | Web app with full OAuth 2.0 configuration |
+| `assets/connected-app-jwt.xml` | JWT bearer / server-to-server |
+| `assets/connected-app-canvas.xml` | Embedding external apps in Salesforce UI (Canvas) |
+| `assets/external-client-app.xml` | ECA header file — all new ECA builds start here |
+| `assets/eca-global-oauth.xml` | ECA global OAuth settings (scopes, PKCE, rotation) |
+| `assets/eca-oauth-settings.xml` | ECA per-app OAuth settings |
+| `assets/eca-policies.xml` | ECA configurable policies |
+
+If you need source-controlled ECA OAuth security metadata, retrieve it from an org first and treat the retrieved file as the schema source of truth:
+```
+sf project retrieve start --metadata ExtlClntAppOauthSecuritySettings:<AppName> --target-org <alias>
+```
+
+### 4. Apply security hardening
+Read `references/security-checklist.md` for the full 120-point security checklist. Favor:
+- Least-privilege scopes
+- Explicit callback URLs
+- PKCE for public clients
+- Certificate-based auth where appropriate
+- Rotation-ready secret / key handling
+- IP restrictions when realistic and maintainable
+
+### 5. Validate deployment readiness
+Read `references/testing-validation-guide.md` before handoff. Confirm:
+- Metadata file naming is correct (see Gotchas below)
+- Scopes are justified
+- Callback and auth model match the real client type
+- Secrets are not embedded in source
+
+### 6. Handle errors
+If deployment fails, check the error output for:
+- `DUPLICATE_VALUE` — a Connected App or ECA with this name already exists; rename or retrieve-then-update instead
+- `INVALID_CROSS_REFERENCE_KEY` — the `externalClientApplication` name in an ECA settings file doesn't match the `.eca-meta.xml` filename exactly
+- `INSUFFICIENT_ACCESS_OR_READONLY` — user lacks the "Manage Connected Apps" permission
+- If any step fails, do not proceed to the next step — surface the error to the user with the specific message above
+
+---
+
+## Rules / Constraints
+
+| Rule | Rationale |
+|---|---|
+| Never commit consumer secrets to source control | Credential exposure risk |
+| Never use `Full` scope by default | Unnecessary privilege; request only what the app needs |
+| Always use PKCE for public clients (mobile, SPA) | Prevents auth code interception |
+| Never use wildcard or overly broad callback URLs | Token interception risk |
+| ECA OAuth security settings must be retrieved from org before editing | File schema is not fully documented; retrieve-first ensures accuracy |
+| Use `<alias>` placeholders in CLI commands, never hardcoded org URLs | Org URLs vary per environment |
+| Detect actual `packageDirectory` from `sfdx-project.json` before writing files | Projects may not use the default `force-app/main/default/` layout |
+
+---
+
+## Metadata Notes That Matter
+
+### Connected App
+Default source location (verify via `sfdx-project.json → packageDirectories`):
+- `<packageDir>/connectedApps/`
+
+### External Client App
+ECA metadata spans multiple top-level source directories. Default locations (verify via `sfdx-project.json`):
+
+| Directory | Metadata type | File suffix |
+|---|---|---|
+| `<packageDir>/externalClientApps/` | `ExternalClientApplication` | `.eca-meta.xml` |
+| `<packageDir>/extlClntAppGlobalOauthSets/` | `ExtlClntAppGlobalOauthSettings` | `.ecaGlblOauth-meta.xml` |
+| `<packageDir>/extlClntAppOauthSettings/` | `ExtlClntAppOauthSettings` | `.ecaOauth-meta.xml` |
+| `<packageDir>/extlClntAppOauthSecuritySettings/` | `ExtlClntAppOauthSecuritySettings` | `.ecaOauthSecurity-meta.xml` |
+| `<packageDir>/extlClntAppOauthPolicies/` | `ExtlClntAppOauthConfigurablePolicies` | `.ecaOauthPlcy-meta.xml` |
+| `<packageDir>/extlClntAppPolicies/` | `ExtlClntAppConfigurablePolicies` | `.ecaPlcy-meta.xml` |
+
+---
+
+## Gotchas
+
+| Gotcha | Detail |
+|---|---|
+| `.ecaGlblOauth` not `.ecaGlobalOauth` | The global OAuth suffix is abbreviated — using the long form will break deployment |
+| `.ecaPlcy` not `.ecaPolicy` | Same abbreviation pattern — the general policy suffix is short form |
+| `.ecaOauthSecurity` for security settings | Use `.ecaOauthSecurity`, not `.ecaSecurity` |
+| ECA OAuth security settings are retrieve-only | Cannot be created from scratch in source — always retrieve from org first |
+| Spring '26: new Connected Apps disabled by default | New orgs block Connected App creation; use ECA unless explicitly required |
+| Consumer key is generated post-deploy | You cannot set the consumer key in metadata — retrieve it after first deployment |
+
+---
+
+## Output Expectations
+
+When finishing, confirm and report in this order:
+
+1. **App type chosen** — Connected App or External Client App
+2. **OAuth flow chosen**
+3. **Files created or updated** — list each metadata file path
+4. **Security decisions** — scopes, PKCE, certs, secrets, IP policy
+5. **Next deployment / testing step**
+
+Suggested output shape:
+```
+App: <name>
+Type: Connected App | External Client App
+Flow: <oauth flow>
+Files: <paths>
+Security: <scopes, PKCE, certs, secrets, IP policy>
+Next step: <deploy, retrieve consumer key, or test auth flow>
+Score: <x>/120
+```
+
+---
+
+## Cross-Skill Integration
+
+| Need | Delegate to | Reason |
+|---|---|---|
+| Named Credential / callout runtime config | [integration-connectivity-generate](../integration-connectivity-generate/SKILL.md) | runtime integration setup |
+| Deploy app metadata | [platform-metadata-deploy](../platform-metadata-deploy/SKILL.md) | org validation and deployment |
+| Apex token or refresh handling | [platform-apex-generate](../platform-apex-generate/SKILL.md) | implementation logic |
+
+---
+
+## Score Guide
+
+| Score | Meaning |
+|---|---|
+| 80+ | production-ready OAuth app config |
+| 54–79 | workable but needs hardening review |
+| < 54 | block deployment until fixed |
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|---|---|
+| `assets/connected-app-basic.xml` | Step 3 — template for simple Connected App with minimal OAuth |
+| `assets/connected-app-oauth.xml` | Step 3 — template for full OAuth 2.0 Connected App |
+| `assets/connected-app-jwt.xml` | Step 3 — template for JWT bearer / server-to-server Connected App |
+| `assets/connected-app-canvas.xml` | Step 3 — template for Canvas app embedding in Salesforce UI |
+| `assets/external-client-app.xml` | Step 3 — ECA header file template |
+| `assets/eca-global-oauth.xml` | Step 3 — ECA global OAuth settings template (PKCE, rotation, callbacks) |
+| `assets/eca-oauth-settings.xml` | Step 3 — ECA per-app OAuth settings template |
+| `assets/eca-policies.xml` | Step 3 — ECA configurable policies template |
+| `references/oauth-flows-reference.md` | Step 2 — detailed OAuth flow comparison and decision guide |
+| `references/security-checklist.md` | Step 4 — full 120-point security scoring checklist |
+| `references/testing-validation-guide.md` | Step 5 — pre-deployment validation and testing guide |
+| `references/migration-guide.md` | When migrating from Connected App to ECA patterns |
+| `references/example-usage.md` | Full end-to-end examples for common OAuth scenarios |

package/skills/integration-connectivity-connected-app-configure/references/example-usage.md

@@ -0,0 +1,256 @@
+<!-- Parent: integration-connectivity-connected-app-configure/SKILL.md -->
+# integration-connectivity-connected-app-configure Examples
+
+Real-world examples of using the integration-connectivity-connected-app-configure skill.
+
+## Example 1: Create a Basic API Integration Connected App
+
+**Request**:
+```
+Use the integration-connectivity-connected-app-configure skill to create a Connected App named "DataSyncIntegration"
+for syncing data with our external ERP system. It needs API access and refresh tokens.
+Contact email: admin@company.com
+```
+
+**Generated Output**:
+- `force-app/main/default/connectedApps/DataSyncIntegration.connectedApp-meta.xml`
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ConnectedApp xmlns="http://soap.sforce.com/2006/04/metadata">
+    <label>DataSyncIntegration</label>
+    <contactEmail>admin@company.com</contactEmail>
+    <description>Data synchronization with external ERP system</description>
+    <oauthConfig>
+        <callbackUrl>https://erp.company.com/oauth/callback</callbackUrl>
+        <isAdminApproved>true</isAdminApproved>
+        <isConsumerSecretOptional>false</isConsumerSecretOptional>
+        <scopes>Api</scopes>
+        <scopes>RefreshToken</scopes>
+    </oauthConfig>
+    <oauthPolicy>
+        <ipRelaxation>ENFORCE</ipRelaxation>
+        <refreshTokenPolicy>infinite</refreshTokenPolicy>
+    </oauthPolicy>
+</ConnectedApp>
+```
+
+**Score**: 95/120 ⭐⭐⭐⭐
+
+---
+
+## Example 2: Create a JWT Bearer App for CI/CD
+
+**Request**:
+```
+Create a Connected App for our CI/CD pipeline using JWT Bearer flow.
+Name it "GitHubActionsDeployment" and use certificate "GH_Actions_Cert".
+```
+
+**Generated Output**:
+- `force-app/main/default/connectedApps/GitHubActionsDeployment.connectedApp-meta.xml`
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ConnectedApp xmlns="http://soap.sforce.com/2006/04/metadata">
+    <label>GitHubActionsDeployment</label>
+    <contactEmail>devops@company.com</contactEmail>
+    <description>CI/CD deployment via GitHub Actions - JWT Bearer flow</description>
+    <oauthConfig>
+        <callbackUrl>https://localhost/oauth/callback</callbackUrl>
+        <certificate>GH_Actions_Cert</certificate>
+        <isAdminApproved>true</isAdminApproved>
+        <isConsumerSecretOptional>true</isConsumerSecretOptional>
+        <scopes>Api</scopes>
+    </oauthConfig>
+    <oauthPolicy>
+        <ipRelaxation>ENFORCE</ipRelaxation>
+        <refreshTokenPolicy>zero</refreshTokenPolicy>
+    </oauthPolicy>
+</ConnectedApp>
+```
+
+**Score**: 108/120 ⭐⭐⭐⭐⭐
+
+---
+
+## Example 3: Create a Mobile App with External Client App
+
+**Request**:
+```
+Create an External Client App for our mobile app "FieldServiceMobile".
+It needs PKCE enabled, refresh tokens, and should be packageable for distribution.
+```
+
+**Generated Files**:
+
+### 1. Header File: `FieldServiceMobile.eca-meta.xml`
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ExternalClientApplication xmlns="http://soap.sforce.com/2006/04/metadata">
+    <contactEmail>mobile-team@company.com</contactEmail>
+    <description>Field Service mobile application for technicians</description>
+    <distributionState>Packageable</distributionState>
+    <isProtected>false</isProtected>
+    <label>FieldServiceMobile</label>
+</ExternalClientApplication>
+```
+
+### 2. Global OAuth: `FieldServiceMobile.ecaGlblOauth-meta.xml`
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ExtlClntAppGlobalOauthSettings xmlns="http://soap.sforce.com/2006/04/metadata">
+    <callbackUrl>fieldservicemobile://oauth/callback</callbackUrl>
+    <externalClientApplication>FieldServiceMobile</externalClientApplication>
+    <isConsumerSecretOptional>true</isConsumerSecretOptional>
+    <isPkceRequired>true</isPkceRequired>
+    <label>Field Service Mobile Global OAuth</label>
+    <shouldRotateConsumerKey>true</shouldRotateConsumerKey>
+    <shouldRotateConsumerSecret>true</shouldRotateConsumerSecret>
+</ExtlClntAppGlobalOauthSettings>
+```
+
+### 3. OAuth Settings: `FieldServiceMobile.ecaOauth-meta.xml`
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ExtlClntAppOauthSettings xmlns="http://soap.sforce.com/2006/04/metadata">
+    <commaSeparatedOauthScopes>Api, RefreshToken, OpenID</commaSeparatedOauthScopes>
+    <externalClientApplication>FieldServiceMobile</externalClientApplication>
+    <label>Field Service Mobile OAuth Settings</label>
+</ExtlClntAppOauthSettings>
+```
+
+### 4. Optional OAuth Security Settings (retrieve-first)
+```bash
+sf project retrieve start \
+  --metadata ExtlClntAppOauthSecuritySettings:FieldServiceMobile \
+  --target-org my-devhub
+```
+
+**Score**: 115/120 ⭐⭐⭐⭐⭐
+
+---
+
+## Example 4: Review Existing Connected Apps
+
+**Request**:
+```
+Review and score my existing Connected Apps for security best practices.
+```
+
+**Process**:
+1. Scan: `Glob: **/*.connectedApp-meta.xml`
+2. Read each file
+3. Validate against scoring criteria
+4. Generate report
+
+**Sample Report**:
+```
+📊 CONNECTED APP SECURITY REVIEW
+════════════════════════════════════════════════════════════════
+
+🔍 Apps Scanned: 3
+📅 Review Date: 2025-01-15
+
+┌────────────────────────────┬────────┬────────┬──────────────────┐
+│ App Name                   │ Score  │ Rating │ Critical Issues  │
+├────────────────────────────┼────────┼────────┼──────────────────┤
+│ LegacyERPConnector         │ 45/120 │ ⭐     │ 3                │
+│ MobileAppV2                │ 82/120 │ ⭐⭐⭐  │ 0                │
+│ DataSyncIntegration        │ 95/120 │ ⭐⭐⭐⭐│ 0                │
+└────────────────────────────┴────────┴────────┴──────────────────┘
+
+🚨 CRITICAL ISSUES
+
+LegacyERPConnector:
+  ❌ Wildcard callback URL detected (https://*)
+  ❌ Full scope granted (overly permissive)
+  ❌ No IP restrictions configured
+  ⚠️ Recommend: Migrate to External Client App
+
+✅ RECOMMENDATIONS
+
+1. LegacyERPConnector: URGENT - Fix security issues or migrate to ECA
+2. MobileAppV2: Enable PKCE for mobile security
+3. DataSyncIntegration: Consider enabling token rotation
+```
+
+---
+
+## Example 5: Migrate Connected App to External Client App
+
+**Request**:
+```
+Migrate our "SalesPortal" Connected App to an External Client App for better security.
+```
+
+**Process**:
+1. Read existing Connected App configuration
+2. Map OAuth settings to ECA structure
+3. Generate all required ECA files
+4. Provide migration checklist
+
+**Output**:
+```
+📦 MIGRATION PLAN: SalesPortal → External Client App
+════════════════════════════════════════════════════════════════
+
+📋 Source Configuration
+   Type: Connected App
+   OAuth Flow: Authorization Code
+   Scopes: Api, RefreshToken, OpenID
+   IP Policy: ENFORCE
+
+📄 Files to Generate:
+   1. SalesPortalECA.eca-meta.xml
+   2. SalesPortalECA.ecaGlblOauth-meta.xml
+   3. SalesPortalECA.ecaOauth-meta.xml
+   4. (Optional) SalesPortalECA.ecaOauthSecurity-meta.xml after retrieve-first validation
+
+🔄 Migration Steps:
+   1. ✓ Generate ECA metadata files
+   2. □ Deploy ECA to DevHub
+   3. □ Generate new Consumer Key/Secret
+   4. □ Update external application with new credentials
+   5. □ Test OAuth flow
+   6. □ Configure policies in subscriber orgs
+   7. □ Deactivate old Connected App
+   8. □ Monitor for 30 days before deletion
+
+⚠️ Breaking Change: New Consumer Key/Secret required
+```
+
+---
+
+## Deployment Commands
+
+### Deploy Connected App
+```bash
+sf project deploy start \
+  --source-dir force-app/main/default/connectedApps \
+  --target-org my-org
+```
+
+### Deploy External Client App
+```bash
+sf project deploy start \
+  --metadata ExternalClientApplication:MyECAName \
+  --metadata ExtlClntAppGlobalOauthSettings:MyECAName \
+  --metadata ExtlClntAppOauthSettings:MyECAName \
+  --target-org my-devhub
+```
+
+### Retrieve Existing Apps
+```bash
+# Connected Apps
+sf project retrieve start \
+  --metadata ConnectedApp:MyAppName \
+  --target-org my-org
+
+# External Client Apps (header + companions)
+sf project retrieve start \
+  --metadata ExternalClientApplication:MyECAName \
+  --metadata ExtlClntAppGlobalOauthSettings:MyECAName \
+  --metadata ExtlClntAppOauthSettings:MyECAName \
+  --target-org my-org
+```