@salesforce/afv-skills 1.45.0 → 1.47.0

package/skills/life-sciences-fieldsalesrep-coordinate/SKILL.md

@@ -0,0 +1,336 @@
+---
+name: life-sciences-fieldsalesrep-coordinate
+description: "Use this skill to run the full end-to-end Life Sciences Cloud setup workflow for field sales rep in sequence. Trigger when the user says 'set up Life Sciences Cloud end to end', 'run the full LSC setup', 'orchestrate Life Sciences Cloud configuration', 'complete LSC setup', 'Life Sciences Cloud full install', 'set up Life Sciences Cloud end to end for field sales rep', 'run the full LSC setup for field sales rep', 'orchestrate Life Sciences Cloud configuration for field sales rep', 'complete LSC setup for field sales rep', or 'Life Sciences Cloud full install for field sales rep'. Executes five stages in order: prerequisites validation, starter config deployment, territory configuration, user provisioning, and sample visit creation — gating each stage on the success of the previous one. DO NOT TRIGGER when: user wants to run only one specific stage (prerequisites, config deploy, territory setup, user provisioning, or visit creation individually)."
+metadata:
+  version: "1.0"
+  minApiVersion: "65.0"
+  domains: ["Life Sciences"]
+  relatedSkills:
+    - life-sciences-prerequisites-validate
+    - life-sciences-territory-configure
+  cliTools:
+    - tool: ["git"]
+      semver: ">=2.25.0"
+    - tool: ["jq"]
+      semver: ">=1.6"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+---
+
+# Life Sciences Cloud End-to-End Orchestrator
+
+Runs the complete Life Sciences Cloud setup workflow as five **stages** in strict sequence, gating each on the success of the previous stage. Each stage delegates to a child skill or a reference workflow, organized internally into **phases** and **steps** (defined under Execution Order below).
+
+## Scope Guard (evaluate FIRST)
+
+Serve **only** requests for the full end-to-end LSC setup. A single stage/phase/step is **never** invokable here — never silently expand a partial ask into the whole flow. Before any work:
+
+- **Unrelated** to LSC setup (at start or mid-run) → do not attempt it. Tell the user you did not understand the request and show what you can help with (full end-to-end LSC setup, or standalone `life-sciences-prerequisites-validate` / `life-sciences-territory-configure`); stop.
+- Stage with its **own standalone skill** — prerequisites (Stage 1) or territory config (Stage 3) → redirect to `life-sciences-prerequisites-validate` / `life-sciences-territory-configure`; stop.
+- Stage with **no standalone skill** — config deploy (2), user provisioning (4), visit creation (5) → explain these run only as part of the full flow, not on their own; stop. Do **not** launch the full flow unless the user then asks for it.
+
+Continue only for the complete end-to-end setup: orchestrating the full flow (prerequisites → config deploy → territory → user provisioning → visit creation) in order with gates. Each stage's actual work is delegated to child skills / reference files.
+
+---
+
+## Required Inputs
+
+Gather before proceeding:
+
+- **Target org**: The org to deploy to — selected by the user from the list of connected orgs, or a freshly authenticated org (see Phase 0). Never assume a default org silently; always have the user confirm or select the target org before any stage runs.
+
+---
+
+## Execution Order (MANDATORY)
+
+> **Terminology:** **Stage** = one of the 5 units of work (1–5), each delegated to a child skill or a reference workflow; **Phase** = a named group of work inside a stage; **Step** = an atomic action inside a phase. So "Stage 2 › Phase 1 › Step 3" reads top-to-bottom.
+
+Run in this order, each gated on the previous (see the full dependency diagram in `references/orchestration-flow.md`):
+
+| # | Stage | Runs | Gate (must pass to advance) | Output |
+|---|-------|------|------------------------------|--------|
+| — | **Setup**: download `.lsc-starter-config/LSStarterConfig` | — | Folder present (MANDATORY — hard stop) | Shared source folder in CWD |
+| 1 | Prerequisites Validation | `life-sciences-prerequisites-validate` skill | All prerequisites PASS | Org confirmed ready |
+| 2 | Starter Config Deploy | `references/stage-2-starter-config-overview.md` | All 13 deploy steps succeed | LSC Custom Profile exists |
+| 3 | Territory Configuration | `life-sciences-territory-configure` skill | Territory model Active + L3 territory | Level-3 territory ID + name |
+| 4 | User Provisioning | `references/stage-4-user-provisioning-overview.md` | User created, permsets + territory assigned | Rep username |
+| 5 | Sample Visit Creation | `references/stage-5-visit-creation-overview.md` | Visit + supporting records created; metadata cache generated | — |
+
+---
+
+## Workflow
+
+### Phase 0 — Org Selection (MANDATORY, runs first)
+
+Before presenting the workflow, establish which org to use. Do this **every time** the user asks to set up Life Sciences Cloud — do not silently reuse the current default org.
+
+1. **List connected orgs**:
+
+   ```bash
+   sf org list --json
+   ```
+
+   Parse the result and present the authenticated orgs (non-expired) to the user as a numbered list — include alias, username, org type (Dev Hub / Sandbox / Scratch / Production), and the default marker if any:
+
+   ```text
+   Connected Orgs — select the target for Life Sciences Cloud setup
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+     1. ls-dev        alice@example.com          (Dev Hub)   [default]
+     2. ls-sandbox    alice@example.com.sandbox  (Sandbox)
+     3. partial-scr   test-xyz@example.com       (Scratch)
+
+     N. Log in to a fresh org (opens a browser to authenticate a new org)
+   ```
+
+2. **Ask the user to choose**: "Which org would you like to use? Enter a number, or choose **N** to log in to a fresh org."
+
+3. **Handle the selection**:
+   - **Existing org chosen** → capture its username/alias as the target org for all subsequent steps.
+   - **Fresh org chosen (option N)** → authenticate a new org interactively: ask for the login URL (My Domain / instance URL, e.g. `https://mydomain.my.salesforce.com`; `https://login.salesforce.com` for production, `https://test.salesforce.com` for a sandbox) and an alias (e.g. `ls-setup`), then **run the login command yourself**:
+
+        ```bash
+        sf org login web --instance-url <user-supplied-url> --alias <user-supplied-alias> --set-default
+        ```
+
+     Do not hand the command to the user to run — execute it directly. It opens a browser on the user's machine for them to complete the web login interactively; the command then returns. After it finishes, re-run `sf org list --json` to confirm the new org, then use it as the target org.
+
+4. **Confirm the target org** back to the user before proceeding: "Using **<alias>** (<username>) as the target org for Life Sciences Cloud setup." Store this in `OrchestrationState.targetOrg`.
+
+> If `sf org list` returns no authenticated orgs, go straight to the fresh-org login flow (option N) — there is nothing to select from.
+
+### Phase 1 — Introduction and Confirmation
+
+1. **Present the workflow** to the user:
+
+   ```text
+   Life Sciences Cloud — Full Setup Workflow
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   This will execute 5 stages in sequence. Each stage is internally
+   organized into phases and steps.
+
+   Stage 1: Validate Prerequisites
+            Checks org settings, permissions, and features
+
+   Stage 2: Deploy Starter Configuration
+            Deploys objects, profiles, config records, layouts, flexipages
+
+   Stage 3: Configure Territories
+            Creates territory type, model, and 3-level hierarchy
+
+   Stage 4: Provision Field Sales Rep User
+            Creates user, assigns profile/permsets, assigns to territory
+
+   Stage 5: Create Sample Visit
+            Logs in as the rep, creates account/provider/visit records,
+            generates the mobile metadata cache
+
+   Target org: <org>
+   ```
+
+2. **Ask for confirmation**: "Ready to begin the full Life Sciences Cloud setup? (yes/no)"
+
+3. **Download the shared source folder ONCE (MANDATORY — hard gate, before any stage).** Both Stage 2 (Starter Config Deploy — metadata + config records) and Stage 5 (Sample Visit Creation — Data CSVs) read from `.lsc-starter-config/LSStarterConfig/`; those stages do NOT download or delete it — the orchestrator owns a single download here and a single delete in Phase 8. Sparse-checkout only that subtree (the repo is large) into the CWD:
+
+   ```bash
+   git clone --no-checkout --depth 1 --filter=blob:none \
+     https://github.com/SalesforceLabs/LSStarterConfig.git lsstarter-tmp
+   cd lsstarter-tmp && git sparse-checkout init --cone \
+     && git sparse-checkout set Codey/LSStarterConfig && git checkout && cd ..
+   mv lsstarter-tmp/Codey ./.lsc-starter-config && rm -rf lsstarter-tmp
+   ```
+
+   > `.lsc-starter-config/LSStarterConfig/` contains its own `sfdx-project.json` (pins `sourceApiVersion: 65.0`) — the deploy step (Phase 3) must run from inside it. If the folder already exists in the CWD (from a prior run), reuse it (skip the download).
+
+4. **Download gate — verify the folder exists before proceeding.** Confirm the download succeeded by checking that `.lsc-starter-config/LSStarterConfig/sfdx-project.json` and `.lsc-starter-config/LSStarterConfig/Data/` are present (e.g. `ls .lsc-starter-config/LSStarterConfig/sfdx-project.json .lsc-starter-config/LSStarterConfig/Data`).
+   - If present → set `sourceFolderDownloaded: true` in `OrchestrationState` and proceed to Phase 2.
+   - If the download failed or the folder/contents are missing → **STOP. Do NOT proceed to any stage** — every stage depends on this folder. Report the failure and stop:
+
+     ```text
+     STOP: Setup cannot start — source download failed
+
+     Could not download .lsc-starter-config/LSStarterConfig from
+     https://github.com/SalesforceLabs/LSStarterConfig.git
+     Likely: no network / GitHub unreachable, git < 2.25 (no sparse-checkout),
+     or insufficient disk space / write permission in the CWD.
+
+     Mandatory prerequisite — no stage can run without it. Fix the cause and
+     re-run, or download the folder manually into the CWD, then re-run.
+     ```
+
+     Leave `sourceFolderDownloaded: false` and do not advance the workflow.
+
+### Phase 2 — Execute Stage 1: Prerequisites Validation
+
+5. **Run the prerequisites validation** following the `life-sciences-prerequisites-validate` skill workflow exactly.
+
+6. **Gate check**: Review the results.
+   - If ALL prerequisites pass → proceed to Stage 2
+   - If ANY prerequisite fails → **stop** and present the failure report
+
+   ```text
+   STOP: Stage 1 FAILED — Prerequisites not met
+   
+   <show the prerequisite failure table>
+   
+   Please resolve the failed prerequisites and re-run this workflow.
+   ```
+
+   Ask the user: "Would you like to continue anyway (skip failed prerequisites), or stop and fix them first?"
+   - If user says stop → end the workflow
+   - If user says continue → proceed with a warning that later stages may fail
+
+### Phase 3 — Execute Stage 2: Starter Config Deploy
+
+7. **Run the starter config deployment** following `references/stage-2-starter-config-overview.md` exactly (all 13 steps in order); read its own reference files as directed.
+
+8. **Gate check**: Verify the LSC Custom Profile exists:
+   ```bash
+   sf data query --query "SELECT Id, Name FROM Profile WHERE Name = 'LSC Custom Profile'" --target-org <org> --json
+   ```
+   - If profile exists → proceed to Stage 3
+   - If profile not found → **stop** and report deployment failure
+
+### Phase 4 — Execute Stage 3: Territory Configuration
+
+9. **Run the territory configuration** following the `life-sciences-territory-configure` skill workflow exactly.
+
+10. **Gate check**: Verify the territory model is Active and level-3 territory exists:
+   ```bash
+   sf data query --query "SELECT Id, Name, DeveloperName, Territory2Model.State FROM Territory2 WHERE ParentTerritory2.ParentTerritory2Id != null AND Territory2Model.State = 'Active'" --target-org <org> --json
+   ```
+   - If level-3 territory found with Active model → capture the territory ID and name, proceed to Stage 4
+   - If not found → **stop** and report the issue
+
+### Phase 5 — Execute Stage 4: User Provisioning
+
+11. **Run the user provisioning** following `references/stage-4-user-provisioning-overview.md` exactly; read its own reference file as directed. Pass the territory information captured from Stage 3.
+
+12. **Gate check**: Verify the user exists, has the correct profile, **all 4** permission sets, and territory assignment. Capture the **rep username** — Stage 5 logs in as this user.
+
+    > **STOP-GATE (Stage 4 completeness).** Do NOT accept "user created" as passing this gate — verify all four facets and STOP if any is short:
+    > ```bash
+    > sf data query --query "SELECT COUNT(Id) c FROM PermissionSetAssignment WHERE AssigneeId = '<newUserId>' AND PermissionSet.IsOwnedByProfile = false" --target-org <org> --json
+    > ```
+    > The permset count MUST be **4** ({LifeSciencesCore, LifeSciencesFieldSalesRepresentative, HealthCloudStarter, LifeSciencesKeyAccountManager}); the user MUST be `IsActive=true` on the `LSC Custom Profile`; and a `UserTerritory2Association` to the level-3 territory MUST exist. If the permset count is < 4 or any facet is missing, Stage 4 did not fully complete — re-run the missing part of `references/stage-4-user-provisioning-overview.md` (its own Phase 4/5 stop-gates cover this) before advancing to Stage 5. A rep missing a permset silently fails visit creation downstream with confusing permission errors.
+
+### Phase 6 — Execute Stage 5: Sample Visit Creation
+
+13. **Run the visit creation** following `references/stage-5-visit-creation-overview.md` exactly; read its own reference files as directed. Pass the rep username captured from Stage 4. This stage:
+    - Logs in as the rep user (`sf org login web`) and creates account, healthcare provider, and visit records (rep-owned), plus territory associations and product master data (admin-owned).
+    - Generates the mobile metadata cache via the Connect API (admin-owned).
+
+    > This stage uses **two identities** — the rep user (from Stage 4) for visit records and the admin for product master data and metadata cache generation. Follow the child skill's rep/admin split exactly.
+
+14. **Gate check**: Verify at least one Visit record was created:
+    ```bash
+    sf data query --query "SELECT Id, Name, AccountId FROM Visit ORDER BY CreatedDate DESC LIMIT 1" --target-org <org> --json
+    ```
+    - If a Visit exists → proceed to the final summary
+    - If no Visit found → **stop** and report the visit-creation failure
+
+### Phase 7 — Final Summary
+
+15. **Display the complete workflow summary** — a "Life Sciences Cloud Setup Complete" header followed by one block per stage (substitute actual values from the run):
+    - **Stage 1**: all org prerequisites confirmed.
+    - **Stage 2**: objects/profiles/config records deployed, `<N>` layouts + `<N>` flexipages deployed, 28 trigger handlers activated.
+    - **Stage 3**: Territory Model `<model name>` (Active); Level-3 Territory `<territory name>`.
+    - **Stage 4**: User `<firstName> <lastName>` (`<username>`); Profile `LSC Custom Profile`; permission sets Life Sciences Core, Life Sciences Field Sales Representative, Health Cloud Starter, Life Sciences Key Account Management; Territory `<territory name>`; admin also assigned to the territory.
+    - **Stage 5**: Account + Healthcare Provider created; Visit `<subject>` (Territory `<territory name>`); product detailing/discussion records; mobile metadata cache generated (Connect API).
+
+    Close with: "The org is ready for Life Sciences Cloud field sales workflows."
+
+### Phase 8 — Cleanup (delete the shared source folder ONCE)
+
+16. **After the final summary** (all 5 stages complete), delete the `.lsc-starter-config` folder downloaded in Phase 1 to leave the working directory clean. Run from the CWD (the parent of `.lsc-starter-config/`):
+
+    ```bash
+    rm -rf .lsc-starter-config
+    ```
+
+    Do this **silently** — do NOT print a cleanup line or mention the folder deletion in the final output. **Skip if the workflow stopped on a failure and the user may resume** — keep the folder until the flow completes so a resumed stage can still read it. This is the single deletion for the whole flow; the child skills never delete it.
+
+---
+
+## State Tracking
+
+Maintain overall orchestration state:
+
+```text
+OrchestrationState = {
+  targetOrg: string,
+  sourceFolderDownloaded: boolean,   // .lsc-starter-config/LSStarterConfig downloaded in Phase 1, deleted in Phase 8
+  stages: [
+    { name: "Prerequisites", status: "pending|running|passed|failed|skipped" },
+    { name: "StarterConfig", status: "pending|running|passed|failed" },
+    { name: "TerritorySetup", status: "pending|running|passed|failed", territoryId?: string, territoryName?: string },
+    { name: "UserProvisioning", status: "pending|running|passed|failed", userId?: string, username?: string },
+    { name: "VisitCreation", status: "pending|running|passed|failed", visitId?: string }
+  ]
+}
+```
+
+---
+
+## Idempotent Stage Transitions & Mid-Flow Changes
+
+Stages are **not re-entrant**. Before executing any stage, check its `status` in `OrchestrationState`: `running` → reply "Stage N is already in progress" and take no action; `passed` → ask for explicit confirmation before re-running; `failed` → re-run (intentional recovery); `pending` → advance. Transition status to `running` at execution **start** (not on user input) so accidental double-confirms never run a stage twice.
+
+If the user requests a change to an earlier stage's inputs **while a later stage is in progress or pending**, run an impact assessment first: acknowledge without applying, identify affected vs. unaffected stages, present options (re-run affected / apply going forward only / cancel), and wait for the decision. Surface destructive-change warnings (an activated territory model can't be deleted; an existing user/records remain).
+
+The full behavior matrix, impact-assessment template, per-change impact mapping, and destructive-change warnings are in `references/state-machine-and-changes.md`.
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|-----------|-----------|
+| Always run Phase 0 org selection first; list connected orgs and let the user pick or log in to a fresh org | User must explicitly choose the target org; never silently reuse the default |
+| Download `.lsc-starter-config/LSStarterConfig` exactly once (Phase 1, MANDATORY hard gate) and delete it exactly once (Phase 8); child skills never download or delete it | Both child skills read from the shared folder — proceeding without it guarantees downstream failures |
+| Execute stages strictly in order 1→5, gating each on prior success | Each stage depends on outputs from previous stages; prevents cascading failures |
+| Never skip Stages 2 or 3, or Stage 4 before Stage 5 | User provisioning depends on profile + territory; visit creation logs in as the Stage-4 rep |
+| Follow each child skill's workflow exactly; capture outputs (IDs, names) for later stages | Child skills have their own confirmations; avoids redundant re-queries |
+| Never re-execute a `running`/`passed` stage without explicit confirmation; transition status to `running` at execution start, not on user input | Race-free idempotency against duplicate "Proceed" messages |
+| Perform impact assessment before applying mid-flow changes | User must see what will break/redo before committing to a change |
+
+---
+
+## Gotchas
+
+| Issue | Resolution |
+|-------|------------|
+| Source download fails in Phase 1 (network/git/disk) | Hard stop — do NOT run any stage. Report the failure (see Phase 1 download gate); fix the cause or download `.lsc-starter-config/LSStarterConfig` manually into the CWD, then re-run |
+| No connected orgs found | `sf org list` returns none — go straight to the fresh-org login (`sf org login web`) in Phase 0 |
+| Fresh-org / rep login needs a browser | Run `sf org login web` yourself (Phase 0 org auth, Stage 5 rep login) — don't hand it to the user. It opens a browser on the user's machine; they complete the web login there and the command returns |
+| Artifacts exist from a prior run (profile, territory, user, config) | The child skills are idempotent/upsert-safe and detect existing records — query the org to confirm, then skip or re-run safely |
+| Visit creation uses two identities (rep + admin) | Product master data and metadata cache are admin-owned; follow the child skill's rep/admin split |
+| Stage re-triggered, or user changes an earlier input mid-flow | See the transition matrix and impact assessment in `references/state-machine-and-changes.md` |
+
+---
+
+## Resume / Partial Re-run
+
+If the user may have already completed some stages (e.g. from a prior session), ask which, then **verify each claimed-complete stage by querying the org** (Stage 1 = ask; 2 = `LSC Custom Profile`; 3 = active model + L3 territory; 4 = user with correct profile/permsets; 5 = a `Visit` record). Skip verified stages and resume from the first incomplete one. Exact detection queries per stage are in `references/orchestration-flow.md` → Resume Logic.
+
+---
+
+## Output Expectations
+
+Deliverables:
+- `.lsc-starter-config/LSStarterConfig` folder downloaded once (Phase 1) and removed once (Phase 8) — both done silently; not reported in the final summary
+- All 5 stages executed successfully (or user-acknowledged skips)
+- Full summary of what was created/configured
+- Org ready for Life Sciences Cloud field sales workflows
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|-------------|
+| `references/orchestration-flow.md` | At start — the dependency diagram, per-stage gate verification queries, resume-detection queries, and timing expectations |
+| `references/state-machine-and-changes.md` | When a stage is re-triggered or the user changes an earlier input mid-flow — the full transition behavior matrix, impact-assessment template + mapping, and destructive-change warnings |
+| `references/stage-2-starter-config-overview.md` | During Stage 2 (Phase 3) — the full 13-step starter-config deploy workflow; it points to its own sibling references as needed |
+| `references/stage-4-user-provisioning-overview.md` | During Stage 4 (Phase 5) — the full field-sales-rep user provisioning workflow; it points to its own sibling reference as needed |
+| `references/stage-5-visit-creation-overview.md` | During Stage 5 (Phase 6) — the full sample-visit creation workflow; it points to its own sibling references as needed |

package/skills/life-sciences-fieldsalesrep-coordinate/references/orchestration-flow.md

@@ -0,0 +1,143 @@
+# Orchestration Flow
+
+## Dependency Diagram
+
+```text
+┌───────────────────────────────────────────────────────────────────┐
+│                    LIFE SCIENCES CLOUD SETUP                       │
+└───────────────────────────────────────────────────────────────────┘
+
+Stage 1: life-sciences-prerequisites-validate
+├── Validates: org settings, permissions, OWD, features
+├── Gate: All 13 checks pass (or user explicitly skips)
+└── Outputs: Confirmation that org is ready
+
+        │
+        ▼
+
+Stage 2: Starter Config Deploy (references/stage-2-starter-config-overview.md)
+├── Deploys: StandardValueSets, objects, profiles, config records,
+│            trigger handlers, layouts, flexipages, application
+├── Gate: LSC Custom Profile exists in org (query confirms)
+└── Outputs: Profile ID for user provisioning
+
+        │
+        ▼
+
+Stage 3: life-sciences-territory-configure
+├── Creates: Territory Type, Territory Model, 3-level hierarchy
+├── Activates: Territory Model (Planning → Active)
+├── Gate: Model state = Active, Level-3 territory queryable
+└── Outputs: Territory2 ID and DeveloperName for user assignment
+
+        │
+        ▼
+
+Stage 4: User Provisioning (references/stage-4-user-provisioning-overview.md)
+├── Creates: Active user with LSC Custom Profile
+├── Assigns: 4 permission sets
+├── Assigns: New user + admin to level-3 territory
+├── Gate: All assignments verified
+└── Outputs: User ID, rep username for visit login
+
+        │
+        ▼
+
+Stage 5: Visit Creation (references/stage-5-visit-creation-overview.md)
+├── Logs in: as the rep user from Stage 4 (sf org login web)
+├── Creates (rep): Account, HealthcareProvider, Visit, ProviderVisit,
+│                  product detailing/discussion
+├── Creates (admin): territory associations, product master data
+├── Generates: mobile metadata cache (Connect API, admin)
+├── Gate: at least one Visit record exists
+└── Outputs: Visit ID, confirmation of records + metadata cache
+```
+
+---
+
+## Gate Verification Queries
+
+### After Stage 1 — Prerequisites
+
+No automated query — the prerequisites skill produces a pass/fail table. Gate on all PASS or explicit user override.
+
+### After Stage 2 — Starter Config
+
+```bash
+sf data query --query "SELECT Id, Name FROM Profile WHERE Name = 'LSC Custom Profile'" --target-org <org> --json
+```
+
+Expected: exactly 1 record returned.
+
+### After Stage 3 — Territory
+
+```bash
+sf data query --query "SELECT Id, Name, DeveloperName, Territory2Model.DeveloperName, Territory2Model.State FROM Territory2 WHERE ParentTerritory2.ParentTerritory2Id != null AND Territory2Model.State = 'Active'" --target-org <org> --json
+```
+
+Expected: at least 1 record (the level-3 territory in an Active model).
+
+### After Stage 4 — User Provisioning
+
+```bash
+sf data query --query "SELECT Id, Name, Username, Profile.Name, IsActive FROM User WHERE Username = '<username>'" --target-org <org> --json
+```
+
+Expected: 1 record with `Profile.Name = 'LSC Custom Profile'` and `IsActive = true`.
+
+```bash
+sf data query --query "SELECT PermissionSet.Label FROM PermissionSetAssignment WHERE AssigneeId = '<userId>' AND PermissionSet.Label IN ('Life Sciences Core', 'Life Sciences Field Sales Representative', 'Health Cloud Starter')" --target-org <org> --json
+```
+
+Expected: 3 records.
+
+```bash
+sf data query --query "SELECT User.Name FROM UserTerritory2Association WHERE Territory2Id = '<territoryId>'" --target-org <org> --json
+```
+
+Expected: at least 2 records (new user + admin).
+
+### After Stage 5 — Visit Creation
+
+```bash
+sf data query --query "SELECT Id, Subject, TerritoryId FROM Visit ORDER BY CreatedDate DESC LIMIT 1" --target-org <org> --json
+```
+
+Expected: at least 1 Visit record (created against the level-3 territory).
+
+Optionally confirm the metadata cache job ran:
+
+```bash
+sf data query --query "SELECT Id, Status, LastModifiedDate FROM LifeSciMobileMetadataRecord ORDER BY LastModifiedDate DESC LIMIT 1" --target-org <org> --json
+```
+
+Expected: a record whose `Status` has transitioned from `ValidationCompleted` to **`Active`** after the async job runs — `Active` is the success state (verified against the org). A transition to `Inactive`, or records stuck at `ValidationCompleted`, means the job failed or never ran — check `IntegrationErrorMessage` and Setup → Apex Jobs.
+
+---
+
+## Resume Logic
+
+When the user re-runs the orchestrator after a partial completion:
+
+| Stage | How to detect completion | Query |
+|------|------------------------|-------|
+| 1 | Cannot detect programmatically | Ask user |
+| 2 | Profile exists | `SELECT Id FROM Profile WHERE Name = 'LSC Custom Profile'` |
+| 3 | Active model + L3 territory | `SELECT Id FROM Territory2 WHERE ParentTerritory2.ParentTerritory2Id != null AND Territory2Model.State = 'Active'` |
+| 4 | User exists with correct profile | `SELECT Id FROM User WHERE Username = '<username>' AND Profile.Name = 'LSC Custom Profile'` |
+| 5 | A Visit record exists | `SELECT Id FROM Visit LIMIT 1` |
+
+If a stage is detected as complete, show the user what was found and ask: "Stage N appears complete (<evidence>). Skip it? (yes/no)"
+
+---
+
+## Timing Expectations
+
+| Stage | Typical Duration | Notes |
+|------|-----------------|-------|
+| 1 - Prerequisites | 1-2 minutes | Read-only queries |
+| 2 - Starter Config | 5-15 minutes | 13 deploy steps, interactive layout/flexipage selection |
+| 3 - Territory Setup | 2-5 minutes | Interactive name confirmation + deploy + activation |
+| 4 - User Provisioning | 2-3 minutes | Interactive user detail collection + creates |
+| 5 - Visit Creation | 3-6 minutes | Interactive rep login + record creation + async metadata cache |
+| **Total** | **13-31 minutes** | Depends on user interaction speed |

package/skills/life-sciences-fieldsalesrep-coordinate/references/stage-2-starter-config-application-flexipage-mapping.md

@@ -0,0 +1,127 @@
+# Application FlexiPage Mapping Reference
+
+## Overview
+
+The application file at `.lsc-starter-config/LSStarterConfig/PackageComponents/applications/lsc4ce__lifeSciencesCommercial.app-meta.xml` contains both `<actionOverrides>` and `<profileActionOverrides>` that reference flexipages. After selective flexipage deployment, the application file must be updated to include only overrides for deployed pages.
+
+## FlexiPage-to-ActionOverride Mapping
+
+The `<actionOverrides>` section uses **managed package prefixed** content names (`lsc4ce__`). These are package-level overrides that reference flexipages from the managed package. They should be **retained as-is** since they reference package flexipages that already exist.
+
+| actionOverrides content | pageOrSobjectType | Corresponding Deployable FlexiPage |
+|------------------------|-------------------|-------------------------------------|
+| lsc4ce__AccountHCP | Account | LSCAccountHCP |
+| lsc4ce__Account_Plan | AccountPlan | Account_Plan3 |
+| lsc4ce__Account_Plan_Objective_Record_Page | AccountPlanObjective | Account_Plan_Objective_Record_Page3 |
+| lsc4ce__Goal_Definition | GoalDefinition | Goal_Definition1 |
+| lsc4ce__Provider_Visit | ProviderVisit | CPVisitLandingPage (Visit-level override) |
+| lsc4ce__Sprint | Sprint | (no direct deployable equivalent) |
+| lsc4ce__TerritoryBusinessPlanRecordPage | TerritoryBusinessPlan | (no direct deployable equivalent) |
+
+## FlexiPage-to-ProfileActionOverride Mapping
+
+The `<profileActionOverrides>` section uses **unmanaged** content names that directly correspond to deployable flexipages. These must be filtered based on user selection.
+
+| profileActionOverrides content | pageOrSobjectType | Record Types | FlexiPage File |
+|-------------------------------|-------------------|--------------|----------------|
+| CPVisitLandingPage | Visit | — | CPVisitLandingPage.flexipage-meta.xml |
+| LSC_Inquiry | Inquiry | Adverse_Event, LSC_General, Medical_Inquiry, (none) | LSC_Inquiry.flexipage-meta.xml |
+| Goal_Definition1 | GoalDefinition | — | Goal_Definition1.flexipage-meta.xml |
+| Account_Plan3 | AccountPlan | — | Account_Plan3.flexipage-meta.xml |
+| Account_Plan_Objective_Record_Page3 | AccountPlanObjective | — | Account_Plan_Objective_Record_Page3.flexipage-meta.xml |
+| LSCAccountHCP | Account | Business, Business_Account, Health_Care_Organization, PersonAccount.Health_Care_Provider, PersonAccount.PersonAccount, (none) | LSCAccountHCP.flexipage-meta.xml |
+| Contact_Point_Address_Record_Page | ContactPointAddress | — | Contact_Point_Address_Record_Page.flexipage-meta.xml |
+| Home_Page_LSC_Default | standard-home | — | Home_Page_LSC_Default.flexipage-meta.xml |
+
+## Update Rules
+
+### actionOverrides
+
+The `<actionOverrides>` entries (lines 3–128 of the app file) reference managed package flexipages (`lsc4ce__*`). These should be **kept as-is** regardless of user selection — they reference pre-existing package pages.
+
+### profileActionOverrides
+
+For `<profileActionOverrides>` (lines 138–665), apply these rules:
+
+1. **Keep** overrides where `<content>` matches a SELECTED flexipage name
+2. **Remove** overrides where `<content>` matches an UNSELECTED flexipage name
+3. Each selected flexipage generates overrides for BOTH profiles (LSC Custom Profile and Admin) and BOTH form factors (Small and Large)
+4. Some flexipages have multiple record-type-specific overrides (e.g., LSC_Inquiry has entries for Adverse_Event, LSC_General, Medical_Inquiry, and a default with no recordType)
+
+### Example: User selects only CPVisitLandingPage and LSC_Inquiry
+
+Keep only these `<profileActionOverrides>` blocks:
+
+```xml
+<!-- CPVisitLandingPage overrides (4 entries: 2 profiles x 2 form factors) -->
+<profileActionOverrides>
+    <actionName>View</actionName>
+    <content>CPVisitLandingPage</content>
+    <formFactor>Small</formFactor>
+    <pageOrSobjectType>Visit</pageOrSobjectType>
+    <type>Flexipage</type>
+    <profile>LSC Custom Profile</profile>
+</profileActionOverrides>
+<profileActionOverrides>
+    <actionName>View</actionName>
+    <content>CPVisitLandingPage</content>
+    <formFactor>Large</formFactor>
+    <pageOrSobjectType>Visit</pageOrSobjectType>
+    <type>Flexipage</type>
+    <profile>LSC Custom Profile</profile>
+</profileActionOverrides>
+<profileActionOverrides>
+    <actionName>View</actionName>
+    <content>CPVisitLandingPage</content>
+    <formFactor>Small</formFactor>
+    <pageOrSobjectType>Visit</pageOrSobjectType>
+    <type>Flexipage</type>
+    <profile>Admin</profile>
+</profileActionOverrides>
+<profileActionOverrides>
+    <actionName>View</actionName>
+    <content>CPVisitLandingPage</content>
+    <formFactor>Large</formFactor>
+    <pageOrSobjectType>Visit</pageOrSobjectType>
+    <type>Flexipage</type>
+    <profile>Admin</profile>
+</profileActionOverrides>
+
+<!-- LSC_Inquiry overrides (many entries: per record type x 2 profiles x 2 form factors) -->
+<!-- Include ALL LSC_Inquiry entries (Adverse_Event, LSC_General, Medical_Inquiry, and default) -->
+```
+
+### Home_Page_LSC_Default Special Case
+
+The Home Page flexipage uses `actionName=Tab` (not `View`) and `pageOrSobjectType=standard-home`:
+```xml
+<profileActionOverrides>
+    <actionName>Tab</actionName>
+    <content>Home_Page_LSC_Default</content>
+    <formFactor>Large</formFactor>
+    <pageOrSobjectType>standard-home</pageOrSobjectType>
+    <type>Flexipage</type>
+    <profile>Admin</profile>
+</profileActionOverrides>
+```
+
+## Static Elements to Always Keep
+
+These elements in the application file are NOT related to flexipages and must always be preserved:
+- `<description>`
+- `<formFactors>`
+- `<isNav*>` settings
+- `<isOmniPinnedViewEnabled>`
+- `<label>`
+- `<navType>`
+- `<subscriberTabs>`
+- `<tabs>`
+- `<uiType>`
+- `<utilityBar>`
+
+## Deploy Command
+
+After updating the application file:
+```bash
+sf project deploy start --source-dir .lsc-starter-config/LSStarterConfig/PackageComponents/applications --target-org <org>
+```