@salesforce/afv-skills 1.30.0 → 1.32.0

package/skills/dx-pkg-post-install-configure/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: dx-pkg-post-install-configure
+description: "Use this skill to automate managed package post-install configuration. Package-agnostic — works with any managed package (LMA, FMA, work.com, Certinia, etc.). TRIGGER when: user installs a managed package and needs post-install configuration, mentions LMA/FMA/work.com post-install setup, asks to configure permission sets/FLS/page layouts for an installed package, says 'post-install', 'package setup', 'configure LMA', 'set up FMA', 'post-install steps'. DO NOT TRIGGER for: standalone permission set assignment (use dx-org-permission-set-assign), generating permission set metadata XML (use platform-permission-set-generate), package installation, or org switching."
+metadata:
+  version: "2.2"
+  minApiVersion: "67.0"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+---
+
+## When to Use This Skill
+
+Use when automating post-install configuration for any Salesforce managed package. This skill reads the package's post-install documentation, discovers available execution methods, and automates the configuration steps — including permission sets, object/field permissions, page layouts, Visualforce page access, and tab settings.
+
+## Input
+
+- **Required:** Package name (e.g., `LMA`, `FMA`, `work.com`)
+- **Optional:** Path to post-install doc (PDF, markdown, URL)
+
+If no doc is provided, ask the user to supply it.
+
+## Workflow
+
+Execute phases in order. Each phase must pass before proceeding.
+
+---
+
+### Phase 1: Discover Available Execution Methods
+
+**Priority order:**
+1. Org-native platform MCP servers (highest — direct org access via Headless 360)
+2. Claude Code external MCP servers (sf-sobject-all, sf-sobject-all-sb, etc.)
+3. sf CLI fallback (always available if authenticated)
+
+#### Step 1A: Resolve org API version
+
+Discover the org's current API version dynamically — never hardcode a version number:
+
+```bash
+sf org display --target-org <alias> --json
+```
+
+From the JSON response, read `result.apiVersion` (e.g., `"67.0"`). Store this value and use it as `v<apiVersion>` in all subsequent REST paths. If the command fails, fall back to the `minApiVersion` declared in this skill's metadata (`67.0`).
+
+#### Step 1B: Check for org-native platform MCP servers
+
+Query the Tooling API for MCP server availability:
+
+```bash
+sf api request rest "/services/data/v<apiVersion>/tooling/query?q=SELECT+Id,DeveloperName,MasterLabel+FROM+McpServerAccess" --target-org <alias>
+```
+
+#### Step 1C: Determine execution method
+
+Check which Claude Code MCP tools are available and authenticated.
+
+**MCP tool prefixes by org type:**
+
+| Org Type | Tool Prefix |
+|---|---|
+| Production | `mcp__sf-sobject-all__` |
+| Sandbox | `mcp__sf-sobject-all-sb__` |
+| Falcon Test (pc-rnd) | `mcp__sf-sobject-all-falcon__` |
+
+If MCP needs auth, call the authenticate tool. If auth fails, fall back to sf CLI.
+
+---
+
+### Phase 2: Verify Authentication & Org Identity
+
+1. Run a lightweight test query (`SELECT Id, Name, IsSandbox FROM Organization`)
+2. If MCP auth fails, automatically fall back to sf CLI
+3. Display org info and ask user to confirm before proceeding
+
+---
+
+### Phase 3: Verify Package Installation
+
+1. Determine the package namespace (ask user if unknown)
+2. Check via Tooling API (`InstalledSubscriberPackage`) — do NOT use `PackageLicense`
+3. If package not found, stop and inform user
+
+---
+
+### Phase 4: Read and Parse Post-Install Document
+
+Read the provided document and extract discrete configuration steps.
+
+**Supported formats:** PDF, markdown, URL (via WebFetch), pasted text.
+
+**Parsing approach:**
+1. Extract each numbered/bulleted step from the document
+2. Present the extracted steps to the user for validation before proceeding
+
+---
+
+### Phase 5: Classify Steps & Interactive Plan Review
+
+For each step extracted from the doc, classify as Automated or Manual.
+
+#### Automation capabilities reference
+
+**Via MCP (sobject-all) or sf CLI CRUD:**
+- Record CRUD on any standard or custom object (PermissionSet, ObjectPermissions,
+  FieldPermissions, SetupEntityAccess, PermissionSetTabSetting, PermissionSetAssignment, etc.)
+
+**Via Metadata API retrieve/deploy (sf CLI):**
+- Page layout modifications (add related lists, fields, sections)
+- Profile settings
+- Custom metadata type records
+
+**Via sf CLI Tooling API:**
+- Tooling queries (InstalledSubscriberPackage, ApexPage, ApexClass, etc.)
+- Any REST-accessible Tooling operation
+
+**Manual (no API path — requires Setup UI):**
+- System permissions not exposed via REST
+- Connected app OAuth configuration
+- Environment Hub linkage
+
+#### Interactive approval
+
+Present the classified plan and let the user choose:
+- **"Approve all"** — Execute all steps as planned
+- **"Let me choose"** — Select which steps to approve/skip
+- **"I have questions"** — Discuss specific steps before deciding
+
+---
+
+### Phase 6: Execute Approved Steps
+
+For each approved step, use the resolved execution method.
+
+#### Execution method reference
+
+| Operation | Via MCP | Via sf CLI |
+|---|---|---|
+| SOQL query | `soqlQuery` tool | `sf data query --query "<SOQL>" --target-org <alias> --json` |
+| Create record | `createSobjectRecord` tool | `sf data create record --sobject <Object> --values "..." --target-org <alias> --json` |
+| Update record | `updateSobjectRecord` tool | `sf data update record --sobject <Object> --record-id <id> --values "..." --target-org <alias> --json` |
+| Describe object | `getObjectSchema` tool | `sf api request rest "/services/data/v<apiVersion>/sobjects/<Object>/describe" --target-org <alias>` |
+| Page layout | N/A | Metadata API retrieve/deploy |
+
+#### Page layout modifications via Metadata API
+
+Use `sf project retrieve start` → edit the layout XML → `sf project deploy start`.
+
+#### Execution rules
+
+- **Idempotency:** Before creating any record, query to check if it already exists. Skip if so.
+- **Report after each step:** Show success count, skipped items, and reasons.
+- **Automatic fallback:** If MCP fails mid-execution, retry via sf CLI.
+- **On failure:** Report error, ask user to retry/skip/stop.
+
+---
+
+### Phase 7: Guide Manual Steps (if any)
+
+If any steps could not be automated, present each with Setup navigation instructions.
+Wait for user confirmation before proceeding to the next.
+
+---
+
+### Phase 8: Summary
+
+Display final summary with step-by-step status, method used, and any skipped items.
+
+---
+
+## Error Handling
+
+- **Auth failure mid-execution:** Stop, ask user to re-auth, offer to resume
+- **Duplicate record errors:** Treat as "already configured", skip and continue
+- **Permission errors:** Report which permission is missing, suggest resolution
+- **Unknown step type:** Ask user to clarify, offer to mark as manual
+
+## Notes
+
+- **Priority: org-native MCP > Claude Code MCP > sf CLI > manual**
+- sf CLI is always a valid fallback for all CRUD and Tooling API operations
+- Page layout modifications are automated via Metadata API retrieve/deploy
+- Always verify org identity before making changes
+- All actions respect the authenticated user's permissions

package/skills/experience-ui-bundle-app-coordinate/SKILL.md

@@ -3,7 +3,17 @@ name: experience-ui-bundle-app-coordinate
 description: "MUST activate when the user wants to build, create, or generate a React application, React app, web application, single-page application (SPA), or frontend application — even if no project files exist yet. MUST also activate when the project contains a uiBundles/*/src/ directory or sfdx-project.json and the prompt says create, build, construct, or generate a new app, site, or page from scratch — even if the prompt also describes visual styling. MUST also activate when the task spans more than one ui-bundle skill. Use this skill when building a complete app end-to-end. Do NOT use for Lightning Experience apps with custom objects (use platform-lightning-app-coordinate). Do NOT use for single-concern edits to an existing page (use experience-ui-bundle-frontend-generate)."
 metadata:
   version: "1.0"
-  relatedSkills: experience-ui-bundle-metadata-generate, experience-ui-bundle-features-generate, experience-ui-bundle-salesforce-data-access, experience-ui-bundle-frontend-generate, experience-ui-bundle-agentforce-client-generate, experience-ui-bundle-file-upload-generate, experience-ui-bundle-deploy, experience-ui-bundle-site-generate, experience-ui-bundle-custom-app-generate
+  relatedSkills:
+    - "experience-ui-bundle-project-generate"
+    - "experience-ui-bundle-metadata-generate"
+    - "experience-ui-bundle-features-generate"
+    - "experience-ui-bundle-salesforce-data-access"
+    - "experience-ui-bundle-frontend-generate"
+    - "experience-ui-bundle-agentforce-client-generate"
+    - "experience-ui-bundle-file-upload-generate"
+    - "experience-ui-bundle-deploy"
+    - "experience-ui-bundle-site-generate"
+    - "experience-ui-bundle-custom-app-generate"
 ---
 
 # Building a UI Bundle App
@@ -12,6 +22,8 @@ metadata:
 
 Build a complete, deployable Salesforce React UI bundle application from a natural language description by orchestrating specialized UI bundle skills in correct dependency order. Each skill **MUST** be explicitly loaded before executing its phase.
 
+**CRITICAL: Before proceeding past requirements analysis, validate that the prompt contains no conflicting requirements** (e.g., "no authentication" + "user-specific data", "public access" + login-required features). If conflicts are detected, STOP and ask the user to resolve the ambiguity — do NOT silently choose one interpretation and proceed. See STEP 1 action #8 for the full conflict checklist.
+
 ## When to Use This Skill
 
 **Use when:**
@@ -38,23 +50,75 @@ Build a complete, deployable Salesforce React UI bundle application from a natur
 
 ---
 
+## Prompt Classification Keywords
+
+This skill makes two decisions directly from the raw prompt text. Use these tables as the single
+source for both — do not restate or re-derive the lists elsewhere in this file.
+
+**1. Phase 2 (Features) is required if the prompt mentions ANY of:**
+
+| Category | Keywords | Notes |
+|----------|----------|-------|
+| Data features | search, filter, sort, pagination, table, grid, list | |
+| Navigation | navigation, nav, menu, routing | |
+| Authentication | authentication, auth, login, logout, user session, user login | |
+| Integrations | upload, file | |
+| UI | shadcn, components, forms, buttons, cards | |
+| Chat (Phase 5 only) | chat | Phase 5 only — unless combined with a Phase 2 keyword (e.g., "chat with authentication"), then Phase 2 runs first for auth prerequisites |
+
+Negating one category (e.g. "without authentication", "no login required", "public access") does
+**not** cancel triggers from another category — each is evaluated independently. Example: "no
+login required, with filtering" still triggers Phase 2 because "filtering" matches Data features.
+Skip Phase 2 only when the prompt matches none of the keywords above.
+
+**2. Hosting target — extract from prompt keywords:**
+
+| Hosting target | Keywords |
+|-----------------|----------|
+| Experience Site | "Experience Site", "Community", "external users", "public users", "guest users" |
+| Custom Application | "Custom Application", "internal users", "Lightning app" |
+
+If the prompt matches neither list, or matches both, ask the user to clarify before proceeding — do not guess.
+
+---
+
 ## Dependency Graph & Build Order
 
+### Phase 0: Template Offer & Bootstrap (Prerequisites)
+
+```text
+Offer prebuilt starter template (experience-ui-bundle-project-generate)
+    v
+If template chosen: scaffold via sf template generate project -- Phase 1 skipped
+    v
+If declined: run scripts/check-sfdx-project.sh
+    v
+If missing: create sfdx-project.json
+    v
+Verify project directory initialized
+```
+
+Offers a faster, less error-prone starting point before building from scratch. If no template is used, ensures an SFDX project exists before attempting to generate a UI bundle — without this, `sf template generate ui-bundle` will fail with a hard error. Always check first — do not assume the project structure exists.
+
+**Action:** Load `experience-ui-bundle-project-generate` and offer the two starter templates. If declined, run `scripts/check-sfdx-project.sh` and report any errors it returns. If the script reports an error, create the missing `sfdx-project.json` before proceeding.
+
 ### Phase 1: Scaffolding (Foundation)
 
 ```text
-UI Bundle scaffold (sf template generate ui-bundle)
+Determine hosting target (Experience Site / Custom Application)
+    v
+UI Bundle scaffold (sf template generate ui-bundle --template reactbasic)
     v
 Install dependencies (npm install)
     v
-Bundle metadata (uibundle-meta.xml, ui-bundle.json)
+Bundle metadata (uibundle-meta.xml with <target>, ui-bundle.json)
     v
 CSP Trusted Sites (if external domains needed)
 ```
 
-Creates the UI bundle directory structure, meta XML, and optional routing/headers config. All subsequent phases require the scaffold to exist.
+Creates the UI bundle directory structure, meta XML (including hosting target), and optional routing/headers config. **CRITICAL**: Hosting target must be determined FIRST because the metadata skill requires `<target>` in Phase 1. All subsequent phases require the scaffold to exist.
 
-### Phase 2: Features (Optional)
+### Phase 2: Features (Required if prompt mentions feature keywords — see "Prompt Classification Keywords" above)
 
 ```text
 Search project code (src/) for existing implementations
@@ -65,10 +129,12 @@ Search, describe, and install features (auth, shadcn, search, navigation, GraphQ
     v
 Resolve conflicts (two-pass: --on-conflict error, then --conflict-resolution)
     v
-Integrate __example__ files into target files, then delete them
+Integrate __examples__ files into target files (verify build succeeds), then delete them
 ```
 
-Installs pre-built, tested feature packages. Skip if the app requires no pre-built features. Always check for an existing feature before building from scratch. Features provide the foundation that UI components build on top of.
+Installs pre-built, tested feature packages. See "Prompt Classification Keywords" above for the full trigger keyword list and negative-phrasing handling — these features provide the foundation that UI components build on top of.
+
+Only skip this phase if the app is truly a minimal "hello world" with no interactive features (no trigger keywords present at all).
 
 ### Phase 3: Data Access (Backend Wiring)
 
@@ -123,16 +189,16 @@ Post-deploy configuration (permissions, profiles, named credentials, connected a
 Import data (if data plan exists)
     v
 Fetch GraphQL schema and run codegen
-*(Re-fetches schema from the deployed org -- required because the remote schema may differ from the local one used in Phase 3)*
+*(Re-fetches schema from the deployed org -- required because the remote schema may differ from the local one used in Phase 3. Guard against an empty or stale result -- Salesforce Edge caching can briefly serve the pre-deploy schema; re-fetch/retry before trusting it as empty and before running codegen)*
     v
 Final UI bundle build (rebuilds with the deployed schema)
 ```
 
 Follows the canonical 7-step deployment sequence. Must deploy metadata before fetching schema. Must assign permissions before schema fetch.
 
-### Phase 7: Hosting Target
+### Phase 7: Hosting Target Infrastructure
 
-Choose **one** of the following based on the app's audience:
+Deploy the hosting target infrastructure determined in Phase 1. Choose **one** of the following based on the app's audience:
 
 #### Phase 7a: Experience Site (External)
 
@@ -144,7 +210,7 @@ Generate site metadata (Network, CustomSite, DigitalExperience)
 Deploy site infrastructure
 ```
 
-Creates the Digital Experience site that hosts the UI bundle. Use when the user wants a public-facing or authenticated site URL for external users.
+Creates the Digital Experience site that hosts the UI bundle. Use when the user wants a public-facing or authenticated site URL for external users. **Note**: The `<target>ExperienceSite</target>` was already set in meta XML during Phase 1.
 
 #### Phase 7b: Custom Application (Internal)
 
@@ -153,17 +219,30 @@ Resolve app properties (appName, appNamespace, appLabel)
     v
 Generate CustomApplication metadata (applications/*.app-meta.xml)
     v
-Add <target>CustomApplication</target> to .uibundle-meta.xml
-    v
 Deploy custom application
 ```
 
-Creates a Custom Application entry in the Lightning App Launcher. Use when the app is for internal users accessing it within Lightning Experience.
+Creates a Custom Application entry in the Lightning App Launcher. Use when the app is for internal users accessing it within Lightning Experience. **Note**: The `<target>CustomApplication</target>` was already set in meta XML during Phase 1.
 
 ---
 
 ## Execution Workflow
 
+### STEP 0: Offer a Prebuilt Template (before scaffolding from scratch)
+
+**Before** analyzing requirements or scaffolding, check whether a prebuilt starter template fits —
+it is faster and less error-prone than building from scratch.
+
+- **Load skill: Invoke `experience-ui-bundle-project-generate`.** It offers two minimal React starter
+  projects (internal / employee-facing and external / customer-facing) and, if the user picks one,
+  generates it into the project directory with `sf template generate project`.
+- **If the user chooses a template:** the scaffolding phase (Phase 1) is effectively done. Skip
+  straight to populating/customizing the project — continue at the phase that matches what they
+  want to change (typically Phase 4 UI, or Phase 3 data access), then Phase 6 deployment.
+- **If the user declines** (wants to start from scratch, or none fit): proceed normally to STEP 1.
+
+Do not skip this step silently — always offer the choice at the start of a from-scratch app build.
+
 ### STEP 1: Requirements Analysis & Planning
 
 **Actions:**
@@ -173,8 +252,12 @@ Creates a Custom Application entry in the Lightning App Launcher. Use when the a
 3. Extract pages and navigation structure
 4. Identify data entities and Salesforce objects needed
 5. Detect feature requirements (authentication, search, file upload, chat)
-6. Determine if an Experience Site is needed
+6. Determine hosting target (Experience Site OR Custom Application) — see "Prompt Classification Keywords" above; if ambiguous, ask user to clarify before proceeding
 7. Identify external domains for CSP registration
+8. **Check for conflicting requirements** — STOP and ask user if any of the following conflicts are detected:
+   - "No authentication" OR "public/guest access" AND "user-specific data" OR "show current user's data" OR "My [Entity]" view
+   - "External users" AND "Custom Application" (Custom Apps are internal-only)
+   - "Public access" AND features requiring login (file upload, user profile, personalization)
 
 > **The plan MUST contain an explicit grounding step before any query authoring.** Do not list
 > guessed object/field names as settled facts and defer verification to codegen. The data-access
@@ -183,6 +266,18 @@ Creates a Custom Application entry in the Lightning App Launcher. Use when the a
 > authors queries first and codegens later is the failure mode that produces guessed fields and
 > hand-stubbed types — do not emit it.
 
+**Before proceeding to Output (Build Plan), validate:**
+
+- [ ] **No conflicting requirements detected** — if conflicts exist (see action #8 above), STOP and report:
+  ```text
+  ERROR: Conflicting requirements detected:
+  - [describe the specific conflict, e.g., "The prompt requires 'no authentication' while also requiring a 'My Cases' view scoped to the current user's identity"]
+  
+  RESOLUTION NEEDED: Please clarify:
+  - [specific question, e.g., "Should the app require login (removing the 'no authentication' requirement), or should all data be public (removing the user-scoped view)?"]
+  ```
+  **Do NOT proceed to build plan generation or any phase execution until this conflict is resolved.**
+
 **Output: Build Plan**
 
 ```text
@@ -190,6 +285,7 @@ UI Bundle App Build Plan: [App Name]
 
 SCAFFOLDING:
 - App name: [PascalCase name]
+- Hosting target: [Experience Site / Custom Application] **REQUIRED**
 - Routing: [SPA rewrites, trailing slash config]
 - External domains: [domains needing CSP registration]
 
@@ -214,10 +310,10 @@ INTEGRATIONS (if applicable):
 
 DEPLOYMENT:
 - Target org: [org alias if known]
-- Hosting target: [Experience Site / Custom Application / none]
 
 SKILL LOAD ORDER:
-1. experience-ui-bundle-metadata-generate
+0. experience-ui-bundle-project-generate (offer a prebuilt template first; if chosen, Phase 1 scaffolding is skipped; if declined, run the Bootstrap check for an existing SFDX project -- no skill load required)
+1. experience-ui-bundle-metadata-generate (determines hosting target FIRST)
 2. experience-ui-bundle-features-generate (if features needed)
 3. experience-ui-bundle-salesforce-data-access (if data access needed)
 4. experience-ui-bundle-frontend-generate
@@ -239,33 +335,45 @@ Execute each phase sequentially. Complete all steps within a phase before moving
 | **3. Verify** | Run lint and build from the UI bundle directory | Catch errors before moving to the next phase |
 | **4. Checkpoint** | Confirm phase completion before proceeding | Ensures dependencies are satisfied for the next phase |
 
-**Do NOT skip step 1 (loading the skill).** Even if you remember the skill's content, skills evolve. Always load the current version.
+**CRITICAL: Do NOT skip step 1 (loading the skill).** Even if you remember the skill's content, skills evolve. Always load the current version. **Skipping or reordering phases produces broken, non-deployable apps.** Phase dependencies are strict and cannot be violated.
 
 ---
 
-**Phase 1 -- Scaffolding**
+**Phase 0 -- Template Offer & Bootstrap** (always, before scaffolding)
+- 1. Load skill: Invoke `experience-ui-bundle-project-generate`
+- 2. Execute: Offer the two starter templates; if the user picks one, generate it into the project dir with `sf template generate project`
+- 3. Decision: If a template was used, the project is scaffolded (including a valid SFDX project structure) — skip Phase 1 and continue at the phase matching the user's customization (usually Phase 4 UI). If declined, proceed to the Bootstrap check below.
+- 4. Bootstrap (no skill load required, only if no template was used): Run `scripts/check-sfdx-project.sh` and report any errors it returns. If the script reports an error, create the SFDX project structure (`sf project generate` or manually create sfdx-project.json).
+- 5. Checkpoint: SFDX project ready -- proceed to Phase 1
+
+**Phase 1 -- Scaffolding** (skip if a template was generated in Phase 0)
 - 1. Load skill: Invoke `experience-ui-bundle-metadata-generate`
-- 2. Execute: Run `sf template generate ui-bundle`, install dependencies (`npm install`), configure meta XML, ui-bundle.json, and CSP trusted sites
-- 3. Verify: Confirm directory structure and metadata files exist
+- 2. Execute: Determine hosting target (Experience Site / Custom Application) FIRST. Run `sf template generate ui-bundle --template reactbasic`, install dependencies (`npm install`), configure meta XML (with `<target>`), ui-bundle.json, and CSP trusted sites.
+- 3. Verify: Confirm directory structure and metadata files exist with hosting target specified
 - 4. Checkpoint: UI bundle scaffold is ready -- proceed to Phase 2
 
-**Phase 2 -- Features** (skip if no pre-built features needed)
+**Phase 2 -- Features** (Required if prompt mentions feature keywords — see "Prompt Classification Keywords" above)
 - 1. Load skill: Invoke `experience-ui-bundle-features-generate`
 - 2. Execute: Install dependencies, search and install features, integrate example files
 - 3. Verify: Run `npm run build` to confirm features integrate cleanly
-- 4. Checkpoint: Features installed -- proceed to Phase 3
+- **Trigger conditions**: See "Prompt Classification Keywords" above for the full keyword list (by category) and how negative phrasing is handled -- negating one category does not cancel triggers from another.
 
 **Phase 3 -- Data Access** (skip if no Salesforce data needed)
 - 1. Load skill: Invoke `experience-ui-bundle-salesforce-data-access`
-- 2. Execute: **Ground entities/fields against the org first** (per the skill), then author queries/mutations **from the verified names**, run codegen, wire into components. Never guess fields or hand-edit generated types.
-- 3. Verify: Run `npx eslint` on files with GraphQL queries
+- 2. Execute: Check preconditions (authenticated org, npm dependencies installed). Fetch schema (`npm run graphql:schema`), guard against empty schema. Look up entities, generate queries/mutations, wire into components.
+- 3. Verify: Run `npx eslint` on files with GraphQL queries. Verify schema is non-empty.
 - 4. Checkpoint: Data layer ready -- proceed to Phase 4
 
-**Phase 4 -- UI**
+**Phase 4 -- UI** (ALWAYS REQUIRED - CANNOT BE SKIPPED)
 - 1. Load skill: Invoke `experience-ui-bundle-frontend-generate`
 - 2. Execute: Build layout, pages, components, navigation. Replace all boilerplate.
+   - If Phase 2 was skipped: Generate UI components from scratch without feature templates
+   - If Phase 3 was skipped: Use mock data or static content for display
+   - Phase 4 MUST execute even if prior phases were skipped
 - 3. Verify: Run lint and build -- 0 errors required
-- 4. Checkpoint: UI complete -- proceed to Phase 5
+- 4. Checkpoint: UI complete -- proceed to Phase 5 if integrations needed, or stop here if building only
+
+⚠️ **CRITICAL**: Phase 4 generates the actual React user interface. Skipping it results in a UI bundle with only metadata and no user-facing pages or components. ALWAYS execute Phase 4 for every UI bundle build.
 
 **Phase 5 -- Integrations** (skip if not requested)
 - 1. Load skill(s): Invoke `experience-ui-bundle-agentforce-client-generate` (5a) and/or `experience-ui-bundle-file-upload-generate` (5b). If both are needed, they are independent and can be executed in parallel.
@@ -275,21 +383,76 @@ Execute each phase sequentially. Complete all steps within a phase before moving
 
 **Phase 6 -- Deployment**
 - 1. Load skill: Invoke `experience-ui-bundle-deploy`
-- 2. Execute: Follow the 7-step deployment sequence (auth, build, deploy, permissions, data, schema, final build)
-- 3. Verify: Confirm deployment succeeds and app is accessible
-- 4. Checkpoint: App deployed -- proceed to Phase 7 if needed
+- 2. Execute: Check preconditions (authenticated org, successful build). Follow the 7-step deployment sequence (auth, build, deploy, permissions, data, schema, final build). When available, prefer using a project-level `scripts/org-setup.mjs` automation script over re-deriving the deployment flow each run. Guard the post-deploy schema re-fetch against an empty/stale result (Edge caching) before running final codegen -- retry rather than trusting an empty schema.
+- 3. Verify: Confirm deployment succeeds, app is accessible, and the re-fetched schema is non-empty
+- 4. Checkpoint: App deployed -- proceed to Phase 7 if hosting target deployment is needed
 
 **Phase 7a -- Experience Site** (skip if not requested or if Custom Application chosen)
 - 1. Load skill: Invoke `experience-ui-bundle-site-generate`
 - 2. Execute: Resolve properties, generate site metadata, deploy
-- 3. Verify: Confirm site URL is accessible
+- 3. Verify: Confirm site URL is accessible (hosting target already verified by `scripts/check-hosting-target.sh` in trigger evaluation)
 - 4. Checkpoint: Site live -- build complete
+- **Trigger conditions**: Run `scripts/check-hosting-target.sh` and check output for "ExperienceSite" OR prompt matches an Experience Site keyword in "Prompt Classification Keywords" above
+- **Note**: The `<target>ExperienceSite</target>` was already set in meta XML during Phase 1 -- do not add it again
 
 **Phase 7b -- Custom Application** (skip if not requested or if Experience Site chosen)
 - 1. Load skill: Invoke `experience-ui-bundle-custom-app-generate`
-- 2. Execute: Resolve app properties, generate CustomApplication metadata, add CustomApplication target to meta XML
-- 3. Verify: Confirm app appears in App Launcher
+- 2. Execute: Resolve app properties, generate CustomApplication metadata
+- 3. Verify: Confirm app appears in App Launcher (hosting target already verified by `scripts/check-hosting-target.sh` in trigger evaluation)
 - 4. Checkpoint: App registered -- build complete
+- **Trigger conditions**: Run `scripts/check-hosting-target.sh` and check output for "CustomApplication" OR prompt matches a Custom Application keyword in "Prompt Classification Keywords" above
+- **Note**: The `<target>CustomApplication</target>` was already set in meta XML during Phase 1 -- do not add it again
+
+### STEP 2.5: Phase Completion Validation
+
+Before proceeding to STEP 3 (Final Summary), validate that all required phases were executed:
+
+**Critical Validation (MUST pass):**
+- [ ] **Phase 0 (Template Offer & Bootstrap) executed**: If no template was used, run `scripts/check-sfdx-project.sh`. If it returns non-zero, STOP and report error:
+  ```text
+  ERROR: No SFDX project detected. Phase 0 (Bootstrap) is REQUIRED before scaffolding.
+  Run `sf project generate` (or create sfdx-project.json) before invoking
+  `sf template generate ui-bundle`.
+  ```
+  If a template was used in Phase 0, this check is satisfied by the template's own scaffolding — skip re-running the script.
+
+- [ ] **Phase 1 hosting target resolved**: Run `scripts/check-hosting-target.sh`. If it returns non-zero, STOP and report error:
+  ```text
+  ERROR: Hosting target was not resolved in Phase 1. A UI bundle without a <target> in its
+  meta XML will not be visible in the org. Determine Experience Site vs Custom Application
+  (see "Prompt Classification Keywords" above; ask the user if ambiguous) before proceeding
+  past Phase 1 -- do not defer this to Phase 7 and do not record "none"/"skipped".
+  ```
+
+- [ ] **Phase 4 (Frontend) executed**: If Phase 4 was NOT executed, STOP and report error:
+  ```text
+  ERROR: Phase 4 (UI/Frontend generation) is REQUIRED for all UI bundle apps.
+  Cannot complete build without generating the React user interface.
+  Please review the phase execution logic and ensure Phase 4 is always executed.
+  ```
+
+- [ ] **Phase 7 hosting infrastructure deployed**: If neither Phase 7a nor Phase 7b was executed, STOP and report error:
+  ```text
+  ERROR: Hosting target infrastructure (Phase 7a Experience Site or Phase 7b Custom
+  Application) was not deployed. The app was built but is not reachable by any user.
+  Exactly one of Phase 7a/7b must run -- it is never optional or "skipped".
+  ```
+
+**Warning Validation (log warnings, but can proceed):**
+- [ ] **Phase 2 execution**: If Phase 2 was skipped but the prompt matches any keyword in "Prompt Classification Keywords" above (data features, navigation, authentication, integrations, or UI category):
+  ```text
+  WARNING: Phase 2 (Features) was skipped but prompt contains feature keywords.
+  This may indicate a trigger detection failure. Generated UI may be missing
+  required feature functionality. Consider re-running with Phase 2 included.
+  ```
+
+- [ ] **Phase 3 execution**: If Phase 3 was skipped but prompt mentions Salesforce objects, "GraphQL", "data", or "query":
+  ```text
+  WARNING: Phase 3 (Data Access) was skipped but prompt mentions Salesforce data.
+  Generated UI may not connect to backend correctly. Verify data access is working.
+  ```
+
+**Proceed to STEP 3 only if all Critical Validation checks pass (Phase 0, hosting target, Phase 4, Phase 7).**
 
 ### STEP 3: Final Summary
 
@@ -299,13 +462,14 @@ After all phases complete, present a build summary:
 UI Bundle App Build Complete: [App Name]
 
 PHASES COMPLETED:
-[x] Phase 1: Scaffolding -- [app name] UI bundle created
+[x] Phase 0: Template Offer & Bootstrap -- [template used: <name> / declined; SFDX project verified/created]
+[x] Phase 1: Scaffolding -- [app name] UI bundle created with hosting target [Experience Site / Custom Application]
 [x] Phase 2: Features -- [list of features installed, or "skipped"]
 [x] Phase 3: Data Access -- [list of entities wired up]
 [x] Phase 4: UI -- [count] pages, [count] components
 [x] Phase 5: Integrations -- [list or "none"]
 [x] Phase 6: Deployment -- deployed to [org]
-[x] Phase 7: Hosting Target -- [Experience Site URL / Custom Application name / "skipped"]
+[x] Phase 7: Hosting Target -- [Experience Site URL / Custom Application name] **(never "skipped" -- Phase 1 requires a target, so exactly one of 7a/7b always runs)**
 
 FILES GENERATED:
 [list key files and their paths]
@@ -321,8 +485,10 @@ NEXT STEPS:
 Before presenting the build as complete, verify:
 
 - [ ] **Scaffold exists**: UI bundle directory with valid meta XML and ui-bundle.json
+- [ ] **Hosting target resolved and deployed**: Meta XML contains `<target>ExperienceSite</target>` or `<target>CustomApplication</target>` (never left unset), and the matching Phase 7a or 7b infrastructure was generated and deployed -- not skipped
 - [ ] **Dependencies installed**: `node_modules/` exists and `package.json` has expected packages
 - [ ] **Build passes**: `npm run build` produces `dist/` with no errors
+- [ ] **Dist content exists**: `dist/` contains index.html, JS/CSS bundles, and assets (not just an empty directory)
 - [ ] **Lint passes**: `npx eslint src/` reports 0 errors
 - [ ] **No boilerplate**: All placeholder text, default titles, and template content has been replaced
 - [ ] **Navigation works**: `appLayout.tsx` has real nav items matching created pages
@@ -337,6 +503,7 @@ Before presenting the build as complete, verify:
 
 - App purpose is too vague to determine pages or data needs
 - User wants features that conflict (e.g., "no authentication" + "show user-specific data")
+- Hosting target cannot be determined (ask: "Is this for internal users (Custom Application) or external users (Experience Site)?")
 - Target org is unknown and deployment is requested
 
 ### Category 2: Log Warning, Continue

package/skills/experience-ui-bundle-app-coordinate/scripts/check-hosting-target.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Check which hosting target is configured in .uibundle-meta.xml files
+
+# Find all .uibundle-meta.xml files
+META_FILES=$(find . -name "*.uibundle-meta.xml" -type f 2>/dev/null)
+
+if [ -z "$META_FILES" ]; then
+  echo "ERROR: No .uibundle-meta.xml files found"
+  exit 1
+fi
+
+# Check for ExperienceSite target
+if echo "$META_FILES" | xargs grep -q '<target>ExperienceSite</target>' 2>/dev/null; then
+  echo "ExperienceSite"
+  exit 0
+fi
+
+# Check for CustomApplication target
+if echo "$META_FILES" | xargs grep -q '<target>CustomApplication</target>' 2>/dev/null; then
+  echo "CustomApplication"
+  exit 0
+fi
+
+# No valid target found
+echo "ERROR: No valid hosting target found in .uibundle-meta.xml"
+exit 1

package/skills/experience-ui-bundle-app-coordinate/scripts/check-sfdx-project.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Check if sfdx-project.json exists and is valid JSON
+
+if [ ! -f sfdx-project.json ]; then
+  echo 'ERROR: sfdx-project.json not found'
+  exit 1
+fi
+
+# Validate JSON format using python (more portable than node)
+if ! python3 -c "import json; json.load(open('sfdx-project.json'))" 2>/dev/null; then
+  echo 'ERROR: sfdx-project.json is not valid JSON'
+  exit 1
+fi
+
+echo 'sfdx-project.json is valid'