@salesforce/afv-skills 1.45.0 → 1.47.0

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

@@ -0,0 +1,241 @@
+---
+name: life-sciences-kam-coordinate
+description: "Use this skill to run the full end-to-end Life Sciences Cloud setup workflow for a key account management (KAM) user in sequence. Trigger when the user says 'set up Life Sciences Cloud end to end for kam user', 'run the full LSC setup for kam user', 'orchestrate Life Sciences Cloud configuration for kam user', 'complete LSC setup for kam user', or 'Life Sciences Cloud full install for kam user'. Executes six stages in order: prerequisites validation, starter config deployment, territory configuration, participant role and sprint creation, KAM data and plan-template (goals, tasks, measures) creation, and KAM user provisioning — gating each stage on the success of the previous one. DO NOT TRIGGER when: the user wants to run only one specific stage individually, or when the request targets a field sales rep rather than a KAM user (use life-sciences-fieldsalesrep-coordinate for that persona)."
+metadata:
+  version: "1.0"
+  minApiVersion: "65.0"
+  domains: ["Life Sciences"]
+  relatedSkills:
+    - life-sciences-fieldsalesrep-coordinate
+    - 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 KAM End-to-End Orchestrator
+
+Runs the complete Life Sciences Cloud setup for a **key account management (KAM)** user as six **stages** in strict sequence, gating each on the previous stage's success. Each stage delegates to a child skill or reference workflow (see Execution Order).
+
+## Scope Guard (evaluate FIRST)
+
+Serve **only** requests for the full end-to-end LSC setup **for a KAM user**. A single stage/phase/step is **never** invokable here — never silently expand a partial ask into the whole flow. Before any work:
+
+- **Field sales rep persona** (not KAM) → redirect to `life-sciences-fieldsalesrep-coordinate`; stop.
+- **Unrelated** to LSC setup (at start or mid-run) → do not attempt it; say you did not understand and show what you can help with (full end-to-end LSC KAM setup, or standalone `life-sciences-prerequisites-validate` / `life-sciences-territory-configure`); stop.
+- **Single stage with its own standalone skill** — prerequisites (1) or territory config (3) → redirect to that skill; stop.
+- **Single stage with no standalone skill** — config deploy (2), participant role/sprint (4), data and plan templates (5), user provisioning (6) → explain these run only inside the full flow; stop. Do **not** launch the full flow unless the user then asks.
+
+Continue only for the complete end-to-end KAM setup: the full flow in order with gates, each stage's work delegated to child skills / reference files.
+
+---
+
+## Required Inputs
+
+- **Target org**: the org to deploy to — selected by the user from connected orgs or a freshly authenticated org (Phase 0). Never assume a default org silently; the user confirms or selects it before any stage runs.
+
+---
+
+## Execution Order (MANDATORY)
+
+> **Terminology:** **Stage** = one of the 6 units of work, each delegated to a child skill/reference; **Phase** = a named group inside a stage; **Step** = an atomic action inside a phase.
+
+Run in this order, each gated on the previous (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` | 13 deploy steps + KAM config records succeed | LSC Custom Profile + KAM/Sprint settings |
+| 3 | Territory Configuration | `life-sciences-territory-configure` skill | Territory model Active + L3 territory | Level-3 territory ID + name |
+| 4 | Participant Role & Sprint | `references/stage-4-participant-role-and-sprint.md` | Participant role + sprint created | Role + Sprint IDs |
+| 5 | KAM Data & Plan Templates | `references/stage-5-data-and-plan-templates-overview.md` | Account/HCP/product/territory data created + goals, template (Final), items, assignment created + goals/template/PATI shared to the leaf territory | Account + product master data + published ActionPlanTemplate |
+| 6 | KAM User Provisioning | `references/stage-6-user-provisioning-overview.md` | User created, permsets + territory assigned; metadata cache generated | KAM username |
+
+---
+
+## Workflow
+
+### Phase 0 — Org Selection (MANDATORY, runs first)
+
+Establish which org to use **every time** — never silently reuse the default org.
+
+1. **List connected orgs** with `sf org list --json`, then present the authenticated (non-expired) orgs as a numbered list (alias, username, org type, default marker), plus an option **N** to log in to a fresh org.
+2. **Ask the user to choose** a number or **N**.
+3. **Handle the selection**:
+   - **Existing org** → capture its username/alias as the target org.
+   - **Fresh org (N)** → ask for the login URL (`https://login.salesforce.com`, `https://test.salesforce.com`, or a My Domain URL) and an alias, then **run the login command yourself**: `sf org login web --instance-url <url> --alias <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 login interactively; the command then returns. After it finishes, re-run `sf org list --json` to confirm.
+4. **Confirm the target org** back to the user and store it in `OrchestrationState.targetOrg`.
+
+> If `sf org list` returns no authenticated orgs, go straight to the fresh-org login (option N).
+
+### Phase 1 — Introduction and Confirmation
+
+1. **Present the workflow** to the user — a "Life Sciences Cloud — Full KAM Setup Workflow" header, the target org, and the 6 stages in order with a one-line summary each: (1) Validate Prerequisites; (2) Deploy Starter Configuration (objects, profiles, config records incl. KAM & Sprint settings, layouts, flexipages); (3) Configure Territories; (4) Create Participant Role & Sprint; (5) Create KAM Data & Plan Templates (account, provider, product, territory data + goals, tasks, measures, published action plan template); (6) Provision KAM User (profile/permsets/territory + mobile metadata cache).
+
+2. **Ask for confirmation**: "Ready to begin the full LSC KAM setup? (yes/no)"
+
+3. **Download the shared source folder FRESH (MANDATORY — hard gate, before any stage).** Stages 2 (metadata + config records) and 5 (Data CSVs) read from `.lsc-starter-config/LSStarterConfig/`; those stages do NOT download or delete it — the orchestrator owns one fresh download here and one delete in Phase 9. **Always re-pull — never reuse an existing folder** (a stale copy would skip newly added components). Delete any pre-existing `.lsc-starter-config` first, then sparse-checkout the subtree fresh:
+
+   ```bash
+   rm -rf .lsc-starter-config lsstarter-tmp
+   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/` has its own `sfdx-project.json` (pins `sourceApiVersion: 65.0`) — deploy steps must run from inside it.
+
+4. **Download gate — verify before proceeding.** Confirm `.lsc-starter-config/LSStarterConfig/sfdx-project.json` and `.lsc-starter-config/LSStarterConfig/Data/` exist (e.g. `ls .lsc-starter-config/LSStarterConfig/sfdx-project.json .lsc-starter-config/LSStarterConfig/Data`).
+   - If present → set `sourceFolderDownloaded: true` and proceed to Phase 2.
+   - If missing/failed → **STOP. Do NOT proceed to any stage** — every stage depends on this folder. Report the failure (likely: no network / GitHub unreachable, git < 2.25, or disk/permission), leave `sourceFolderDownloaded: false`, and do not advance. Fix the cause and re-run, or download the folder manually into the CWD.
+
+### Phase 2 — Execute Stage 1: Prerequisites Validation
+
+5. **Run the prerequisites validation** following the `life-sciences-prerequisites-validate` skill workflow exactly.
+
+6. **Gate check**: If ALL prerequisites pass → proceed to Stage 2. If ANY fails → **stop**, present the failure table, and ask: "Continue anyway (skip failed prerequisites), or stop and fix them first?" Stop → end the workflow. 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 deploy steps + the KAM/Sprint config-record edits); read its own reference files as directed. The KAM adaptation deploys only the KAM-relevant layouts (4) and flexipages (6) — all of them, automatically, with no selection prompt — and confirms the StandardValueSet picklist values with the admin (three business-framed groups) BEFORE deploying them, then writes those confirmed values into the `KAMSettings_OrgLevel` and `SprintSettings_OrgLevel` config records.
+
+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 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. If an active territory model already exists, use it and show the hierarchy rather than creating a new one.
+
+10. **Gate check**: Verify the territory model is Active and a 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 found → **capture the level-3 territory ID + name** (`OrchestrationState.territoryId`) and tell the user this leaf territory is the single territory reused for Stage 5 (ProductTerritoryAvailability) and Stage 6 (UserTerritory2Association for both admin and KAM user). Proceed to Stage 4.
+    - If not found → **stop** and report the issue.
+
+### Phase 5 — Execute Stage 4: Participant Role & Sprint
+
+11. **Create the participant role and sprint** following `references/stage-4-participant-role-and-sprint.md` exactly. Only the `MasterLabel`/`Name` fields are confirmed with the admin; all other fields are auto-derived and shown for confirmation.
+
+12. **Gate check**: Verify a `ParticipantRole` (`DeveloperName = 'Rep_Execution_Specialist'`, `IsActive = true`) and a `Sprint` (Status `Not Started`) exist. If either is missing → **stop** and report.
+
+### Phase 6 — Execute Stage 5: KAM Data & Plan Templates
+
+Both parts run as the admin, in order, from the single reference `references/stage-5-data-and-plan-templates-overview.md` (Part A = data, Part B = plan templates).
+
+13. **Create the KAM data (Part A)** following the reference exactly. Pass the Stage-3 level-3 territory. Creates (from the Data CSVs): Account, HealthcareProvider, ObjectTerritory2Association, ProviderAcctTerritoryInfo, Product2, LifeSciMarketableProduct, ContactPointAddress, ProductTerritoryAvailability.
+
+14. **Part A gate check**: Verify the Account, `LifeSciMarketableProduct`, and `ProductTerritoryAvailability` (on the Stage-3 territory) exist; capture the `LifeSciMarketableProduct` ID (Part B uses it). If any missing → **stop**.
+
+15. **Create the goals, tasks, measures, and action plan template (Part B)** following the same reference exactly (stay on the admin login). Creates 2 `GoalDefinition` records, a `GoalDefinitionProduct`, an `ActionPlanTemplate` (+ auto `ActionPlanTemplateVersion`), 3 `ActionPlanTemplateItem` records, publishes the template (status → Final), creates an `ActionPlanTemplateAssignment`, and shares the 2 `GoalDefinition` records, the `ActionPlanTemplate`, and both `ProviderAcctTerritoryInfo` records to the Stage-3 leaf-territory **Group** (5 manual shares total) so the KAM user reaches them through the territory. Only the record **names** are confirmed with the admin.
+
+16. **Part B gate check**: Verify the template is published (a `Final` `ActionPlanTemplateVersion` exists), an `ActionPlanTemplateAssignment` exists, and the leaf-territory shares exist (2 `GoalDefinitionShare` + 1 `ActionPlanTemplateShare` + 2 `ProviderAcctTerritoryInfoShare` whose `UserOrGroupId` is the Stage-3 territory Group). If not → **stop**.
+
+### Phase 7 — Execute Stage 6: KAM User Provisioning
+
+17. **Provision the KAM user** following `references/stage-6-user-provisioning-overview.md` exactly. Pass the Stage-3 level-3 territory. Creates a user whose username contains `kam`, assigns the permission sets **Health Cloud Starter**, **Life Sciences Key Account Management**, **Life Sciences Field Sales Representative**, and **Life Sciences Core**, assigns **both the admin and the KAM user** to the level-3 territory (confirm with admin — MUST be the same territory used for ProductTerritoryAvailability in Stage 5), and generates the mobile metadata cache via the Connect API.
+
+18. **Gate check (STOP-GATE — Stage 6 completeness).** Do NOT accept "user created" as passing. Verify the user is `IsActive=true` on `LSC Custom Profile`, has a `UserTerritory2Association` to the Stage-3 territory, the metadata cache reached `Status='Active'`, and the assigned-permset count is **4** ({HealthCloudStarter, LifeSciencesKeyAccountManager, LifeSciencesFieldSalesRepresentative, LifeSciencesCore}):
+    ```bash
+    sf data query --query "SELECT COUNT(Id) c FROM PermissionSetAssignment WHERE AssigneeId = '<newUserId>' AND PermissionSet.IsOwnedByProfile = false" --target-org <org> --json
+    ```
+    If < 2, or the territory assignment or metadata cache is missing, re-run the missing part before finishing.
+
+### Phase 8 — Final Summary, Cleanup & On-Device Validation
+
+19. **Display the complete workflow summary** — a "Life Sciences Cloud KAM Setup Complete" header, then one block per stage with actual values: (1) prerequisites confirmed; (2) objects/profiles/config records deployed, KAM & Sprint settings written, layouts + flexipages, 28 trigger handlers; (3) Territory Model `<model>` (Active) + Level-3 `<territory>`; (4) Participant Role `Rep Execution Specialist` + Sprint `<name>`; (5) Account + HCP, product master data, ProductTerritoryAvailability on `<territory>`, 2 Goal Definitions, ActionPlanTemplate `<name>` (Final) + 3 items + assignment, goals + template + 2 PATI shared to territory `<territory>`; (6) User `<name>` (`<username>`) on `LSC Custom Profile`, permsets Health Cloud Starter + Life Sciences Key Account Management + Life Sciences Field Sales Representative + Life Sciences Core, Territory `<territory>` (admin + KAM), mobile metadata cache generated. Close: "The org is ready for Life Sciences Cloud key account management workflows."
+
+20. **Cleanup — delete the shared source folder ONCE.** After the final summary (all 6 stages complete), run from the CWD:
+
+    ```bash
+    rm -rf .lsc-starter-config
+    ```
+
+    Do this **silently** — do NOT print a cleanup line or mention the deletion. **Skip if the workflow stopped on a failure and the user may resume** — keep the folder so a resumed stage can still read it. This is the single deletion for the whole flow; child skills never delete it.
+
+21. **Display the on-device (iPad) validation script and await confirmation.** Once the metadata cache is `Status='Active'` and the summary is shown, display the script **verbatim** from `references/stage-6-ipad-validation-script.md` (the login uses the Stage-6 KAM user's credentials), then **wait for the user to confirm** the on-device steps succeeded. Once confirmed, the setup is complete.
+
+---
+
+## State Tracking
+
+Maintain overall orchestration state:
+
+```text
+OrchestrationState = {
+  targetOrg: string,
+  sourceFolderDownloaded: boolean,   // downloaded in Phase 1, deleted in Phase 9
+  territoryId?: string, territoryName?: string,   // captured in Stage 3, reused in Stages 5 & 6
+  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: "ParticipantSprint",   status: "pending|running|passed|failed", roleId?: string, sprintId?: string },
+    { name: "DataAndPlanTemplates",status: "pending|running|passed|failed", accountId?: string, marketableProductId?: string, templateVersionId?: string },
+    { name: "UserProvisioning",    status: "pending|running|passed|failed", userId?: string, username?: string }
+  ]
+}
+```
+
+---
+
+## Idempotent Stage Transitions & Mid-Flow Changes
+
+Stages are **not re-entrant**. Before executing any stage, check its `status`: `running` → reply "Stage N is already in progress" and take no action; `passed` → ask explicit confirmation before re-running; `failed` → re-run (recovery); `pending` → advance. Set `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/pending**, run an impact assessment first: acknowledge without applying, identify affected vs. unaffected stages, present options (re-run affected / apply forward only / cancel), and wait for the decision. Surface destructive-change warnings (an activated territory model can't be deleted; an existing user/records/published template 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
+
+- **Org**: run Phase 0 org selection first; never silently reuse the default org.
+- **Shared folder**: download `.lsc-starter-config/LSStarterConfig` exactly once (Phase 1 hard gate), delete it exactly once (Phase 9); child skills never touch it — Stages 2 and 5 read it, so proceeding without it fails downstream.
+- **Order**: execute stages strictly 1→6, gating each on prior success; capture each stage's outputs (IDs, names) for later stages.
+- **Territory invariant**: reuse the SAME Stage-3 level-3 territory (`OrchestrationState.territoryId`) for Stage 5 (ProductTerritoryAvailability) and Stage 6 (user alignment), or the KAM user sees no data.
+- **Confirmation**: confirm only the fields each stage marks admin-confirmable; auto-derive the rest and show for confirmation.
+- **Idempotency**: never re-execute a `running`/`passed` stage without confirmation (set `running` at execution start); impact-assess before applying mid-flow changes.
+
+---
+
+## Gotchas
+
+| Issue | Resolution |
+|-------|------------|
+| Source download fails in Phase 1 | Hard stop — do NOT run any stage. Fix the cause or download `.lsc-starter-config/LSStarterConfig` manually into the CWD, then re-run |
+| No connected orgs found | Go straight to the fresh-org login (`sf org login web`) in Phase 0 |
+| Artifacts exist from a prior run | Child skills/references are idempotent/upsert-safe — query to confirm, then skip or re-run |
+| Stage re-triggered, or earlier input changed mid-flow | See `references/state-machine-and-changes.md` |
+
+---
+
+## Resume / Partial Re-run
+
+If the user may have already completed some stages, ask which, then **verify each claimed-complete stage by querying the org** (1 = ask; 2 = `LSC Custom Profile`; 3 = active model + L3 territory; 4 = `ParticipantRole` + `Sprint`; 5 = Account + `ProductTerritoryAvailability` + `Final` version + assignment; 6 = `kam` user + permsets + territory), skip verified stages, and resume from the first incomplete one. Exact per-stage queries: `references/orchestration-flow.md` → Resume Logic.
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|-------------|
+| `references/orchestration-flow.md` | At start — dependency diagram, gate + resume-detection queries, timing |
+| `references/state-machine-and-changes.md` | On a re-triggered stage or a mid-flow input change |
+| `references/stage-2-starter-config-overview.md` | Stage 2 — 13-step deploy + KAM/Sprint config records (points to sibling refs) |
+| `references/stage-4-participant-role-and-sprint.md` | Stage 4 — participant role + sprint |
+| `references/stage-5-data-and-plan-templates-overview.md` | Stage 5 — KAM data creation (Part A, points to its data ref) + goals, tasks, measures, action plan template (Part B) |
+| `references/stage-6-user-provisioning-overview.md` | Stage 6 — user provisioning + metadata cache (points to sibling refs) |
+| `references/stage-6-ipad-validation-script.md` | Final step — on-device (iPad) validation script shown after the metadata cache is Active |

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

@@ -0,0 +1,152 @@
+# Orchestration Flow (KAM)
+
+## Dependency Diagram
+
+```text
+┌───────────────────────────────────────────────────────────────────┐
+│              LIFE SCIENCES CLOUD KAM END-TO-END SETUP              │
+└───────────────────────────────────────────────────────────────────┘
+
+Setup: download .lsc-starter-config/LSStarterConfig (coordinator, once)
+        │
+        ▼
+Stage 1: life-sciences-prerequisites-validate
+├── Validates: org settings, permissions, OWD, features
+├── Gate: All 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 (10 confirmed), objects, profiles, config records
+│            (incl. KAMSettings + SprintSettings), trigger handlers,
+│            4 KAM layouts, 6 KAM flexipages, application
+├── Gate: LSC Custom Profile exists in org (query confirms)
+└── Outputs: Profile ID; KAM/Sprint config records written
+        │
+        ▼
+Stage 3: life-sciences-territory-configure
+├── Creates (or reuses) Territory Type, Territory Model, 3-level hierarchy
+├── Activates: Territory Model (Planning → Active)
+├── Gate: Model state = Active, Level-3 territory queryable
+└── Outputs: Level-3 Territory2 ID + name  ← reused in Stages 5 and 6
+        │
+        ▼
+Stage 4: Participant Role & Sprint (references/stage-4-participant-role-and-sprint.md)
+├── Creates: ParticipantRole "Rep Execution Specialist", Sprint "Sprint 1 …"
+├── Gate: ParticipantRole (IsActive) + Sprint (Not Started) exist
+└── Outputs: Role ID, Sprint ID
+        │
+        ▼
+Stage 5: KAM Data & Plan Templates (references/stage-5-data-and-plan-templates-overview.md) — as ADMIN
+├── Part A creates: Account, HealthcareProvider, ObjectTerritory2Association,
+│            ProviderAcctTerritoryInfo, Product2, LifeSciMarketableProduct,
+│            ContactPointAddress, ProductTerritoryAvailability (on Stage-3 territory)
+├── Part B creates: 2 GoalDefinition, GoalDefinitionProduct, ActionPlanTemplate
+│            (+ auto Version), 3 ActionPlanTemplateItem, ActionPlanTemplateAssignment;
+│            publishes ActionPlanTemplate (status → Final);
+│            shares goals + template + both PATI records to the leaf-territory Group
+│            (2 GoalDefinitionShare + 1 ActionPlanTemplateShare + 2 ProviderAcctTerritoryInfoShare)
+├── Gate: Account + LifeSciMarketableProduct + ProductTerritoryAvailability exist,
+│         Final ActionPlanTemplateVersion + ActionPlanTemplateAssignment exist,
+│         and the leaf-territory shares exist
+└── Outputs: Account ID, LifeSciMarketableProduct ID, ActionPlanTemplateVersion ID
+        │
+        ▼
+Stage 6: KAM User Provisioning (references/stage-6-user-provisioning-overview.md)
+├── Creates: Active user (username contains "kam") on LSC Custom Profile
+├── Assigns: 4 permission sets (HealthCloudStarter, LifeSciencesKeyAccountManager, LifeSciencesFieldSalesRepresentative, LifeSciencesCore)
+├── Assigns: KAM user + admin to the Stage-3 level-3 territory
+├── Generates: mobile metadata cache (Connect API, admin)
+├── Gate: user active, 4 permsets, territory assigned, metadata cache Active
+└── Outputs: KAM username, login URL
+```
+
+---
+
+## 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.
+
+### After Stage 3 — Territory
+```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
+```
+Expected: at least 1 record (the level-3 territory in an Active model). Capture its Id + Name.
+
+### After Stage 4 — Participant Role & Sprint
+```bash
+sf data query --query "SELECT Id, DeveloperName, IsActive FROM ParticipantRole WHERE DeveloperName = 'Rep_Execution_Specialist'" --target-org <org> --json
+sf data query --query "SELECT Id, Name, Status FROM Sprint ORDER BY CreatedDate DESC LIMIT 1" --target-org <org> --json
+```
+Expected: ParticipantRole `IsActive=true`; Sprint with `Status='Not Started'`.
+
+### After Stage 5 — KAM Data & Plan Templates
+
+Part A (data):
+```bash
+sf data query --query "SELECT Id FROM LifeSciMarketableProduct ORDER BY CreatedDate DESC LIMIT 1" --target-org <org> --json
+sf data query --query "SELECT Id, ProductId, TerritoryId FROM ProductTerritoryAvailability ORDER BY CreatedDate DESC LIMIT 1" --target-org <org> --json
+```
+Expected: a LifeSciMarketableProduct and a ProductTerritoryAvailability on the Stage-3 territory. Capture the LifeSciMarketableProduct Id.
+
+Part B (plan templates):
+```bash
+sf data query --query "SELECT Id, ActionPlanTemplateId, Status FROM ActionPlanTemplateVersion WHERE Status = 'Final' ORDER BY CreatedDate DESC LIMIT 1" --target-org <org> --json
+sf data query --query "SELECT Id FROM ActionPlanTemplateAssignment ORDER BY CreatedDate DESC LIMIT 1" --target-org <org> --json
+sf data query --query "SELECT Id, ParentId, UserOrGroupId FROM GoalDefinitionShare WHERE RowCause = 'Manual' ORDER BY CreatedDate DESC LIMIT 2" --target-org <org> --json
+sf data query --query "SELECT Id, ParentId, UserOrGroupId FROM ActionPlanTemplateShare WHERE RowCause = 'Manual' ORDER BY CreatedDate DESC LIMIT 1" --target-org <org> --json
+sf data query --query "SELECT Id, ParentId, UserOrGroupId FROM ProviderAcctTerritoryInfoShare WHERE RowCause = 'Manual' ORDER BY CreatedDate DESC LIMIT 2" --target-org <org> --json
+```
+Expected: a `Final` ActionPlanTemplateVersion, an ActionPlanTemplateAssignment, and the leaf-territory shares (2 GoalDefinitionShare + 1 ActionPlanTemplateShare + 2 ProviderAcctTerritoryInfoShare) whose `UserOrGroupId` is the Stage-3 territory Group.
+
+### After Stage 6 — User Provisioning
+```bash
+sf data query --query "SELECT Id, Name, Username, Profile.Name, IsActive FROM User WHERE Username = '<username>'" --target-org <org> --json
+sf data query --query "SELECT COUNT(Id) c FROM PermissionSetAssignment WHERE AssigneeId = '<userId>' AND PermissionSet.IsOwnedByProfile = false" --target-org <org> --json
+sf data query --query "SELECT User.Name FROM UserTerritory2Association WHERE Territory2Id = '<territoryId>'" --target-org <org> --json
+```
+Expected: user `IsActive=true` on `LSC Custom Profile`; permset count **4**; ≥2 territory associations (KAM user + admin).
+
+Confirm the metadata cache reached `Active`:
+```bash
+sf data query --query "SELECT Id, Status, LastModifiedDate FROM LifeSciMobileMetadataRecord ORDER BY LastModifiedDate DESC LIMIT 1" --target-org <org> --json
+```
+Expected: `Status='Active'` after the async job runs. `Inactive`, or stuck at `ValidationCompleted`, means failure — 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 | Role + Sprint exist | `SELECT Id FROM ParticipantRole WHERE DeveloperName='Rep_Execution_Specialist'`; `SELECT Id FROM Sprint LIMIT 1` |
+| 5 | Data + published template + territory shares exist | `SELECT Id FROM ProductTerritoryAvailability LIMIT 1`; `SELECT Id FROM ActionPlanTemplateVersion WHERE Status='Final' LIMIT 1`; `SELECT Id FROM ActionPlanTemplateShare WHERE RowCause='Manual' LIMIT 1` |
+| 6 | KAM user exists | `SELECT Id FROM User WHERE Username LIKE '%kam%' AND Profile.Name = 'LSC Custom Profile'` |
+
+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 | 6-16 minutes | 13 deploy steps + SVS confirmations + KAM/Sprint config records |
+| 3 - Territory Setup | 2-5 minutes | Interactive name confirmation + deploy + activation (or reuse) |
+| 4 - Participant Role & Sprint | 1-2 minutes | 2 record creates + confirmation |
+| 5 - Data & Plan Templates | 6-12 minutes | Part A: 8 object creates from CSVs (admin); Part B: goals, template, items, publish, assignment |
+| 6 - User Provisioning | 3-6 minutes | User + permsets + territory + async metadata cache |
+| **Total** | **19-43 minutes** | Depends on user interaction speed |

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

@@ -0,0 +1,79 @@
+# Application FlexiPage Mapping Reference (KAM)
+
+## 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 the KAM flexipages are deployed (Step 12), the application file must be updated to include only overrides for deployed pages.
+
+## The Six KAM FlexiPages
+
+For the KAM workflow, only these six flexipages are offered and confirmed with the user (see `stage-2-starter-config-overview.md`, Step 12):
+
+| FlexiPage | pageOrSobjectType | Record Types |
+|-----------|-------------------|--------------|
+| Home_Page_LSC_Default | standard-home | — |
+| LSCAccountHCP | Account | Business, Business_Account, Health_Care_Organization, PersonAccount.Health_Care_Provider, PersonAccount.PersonAccount, (none) |
+| Contact_Point_Address_Record_Page | ContactPointAddress | — |
+| Account_Plan_Objective_Record_Page3 | AccountPlanObjective | — |
+| Account_Plan3 | AccountPlan | — |
+| Goal_Definition1 | GoalDefinition | — |
+
+## actionOverrides (keep as-is)
+
+The `<actionOverrides>` section uses **managed package prefixed** content names (`lsc4ce__`). These are package-level overrides referencing managed-package flexipages that already exist; **retain them as-is** regardless of selection. The KAM-relevant ones:
+
+| 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 |
+
+## profileActionOverrides (filter to deployed pages)
+
+The `<profileActionOverrides>` section uses **unmanaged** content names that directly correspond to deployable flexipages. Apply these rules:
+
+1. **Keep** overrides where `<content>` matches a DEPLOYED (confirmed) 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. `LSCAccountHCP`).
+
+### Example: LSCAccountHCP profileActionOverrides block
+
+```xml
+<profileActionOverrides>
+    <actionName>View</actionName>
+    <content>LSCAccountHCP</content>
+    <formFactor>Large</formFactor>
+    <pageOrSobjectType>Account</pageOrSobjectType>
+    <recordType>Health_Care_Organization</recordType>
+    <type>Flexipage</type>
+    <profile>LSC Custom Profile</profile>
+</profileActionOverrides>
+```
+Repeat per record type × form factor (Small/Large) × profile (LSC Custom Profile/Admin). Include the record-type variants listed in the table above plus the default (no `<recordType>`) entry.
+
+### 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>
+```

package/skills/life-sciences-kam-coordinate/references/stage-2-starter-config-deploy-commands.md

@@ -0,0 +1,131 @@
+# Deploy Commands Reference
+
+Exact CLI commands for each foundation deployment step. All commands use `--target-org <org>` where `<org>` is the user-provided org alias or username.
+
+> **Working directory (required):** Run every `sf project deploy start` command from **inside the `.lsc-starter-config/LSStarterConfig/` project root** (the directory containing `sfdx-project.json`). `sf` searches the current directory and its ancestors — never its descendants — for `sfdx-project.json`, which pins `sourceApiVersion: 65.0`. If you run from a parent directory (or an unrelated repo), `sf` cannot find the project file, silently falls back to **API 60.0**, and profile deploys fail with `Property 'viewAllFields' not valid in version 60.0` (LSC profiles use 65.0-only permissions). The `.lsc-starter-config/LSStarterConfig/...` paths shown below are for readability — `cd` into `.lsc-starter-config/LSStarterConfig/` first and use paths relative to it (e.g. `PackageComponents/objects`).
+
+## Step 1: StandardValueSets
+
+```bash
+sf project deploy start --source-dir .lsc-starter-config/LSStarterConfig/PackageComponents/standardValueSets --target-org <org>
+```
+
+Expected files deployed:
+
+Generic Health-Cloud value sets:
+- AccountRating.standardValueSet-meta.xml
+- CPSSocialPlatformProvider.standardValueSet-meta.xml
+- CareSpecialtySpecialtyType.standardValueSet-meta.xml
+- CasePriority.standardValueSet-meta.xml
+- CaseStatus.standardValueSet-meta.xml
+- HProviderProviderClass.standardValueSet-meta.xml
+- HProviderProviderType.standardValueSet-meta.xml
+- HealthcareProviderStatus.standardValueSet-meta.xml
+- InquiryTypeEnum.standardValueSet-meta.xml
+- PAAffiliationRole.standardValueSet-meta.xml
+
+KAM value sets (the ones confirmed with the admin before deploy — see Step 1 in `stage-2-starter-config-overview.md`). Confirmations A & B cover the first eight; `ActionPlanState` and `GoalAssignmentStatus` deploy with their shipped defaults (no prompt):
+- StakeholderRoleType.standardValueSet-meta.xml
+- StakeholderInfluenceLevel.standardValueSet-meta.xml
+- StakeholderStrength.standardValueSet-meta.xml
+- TerritoryBusinessPlanStatus.standardValueSet-meta.xml
+- AccountPlanStatus.standardValueSet-meta.xml
+- AccPlanObjectiveStatus.standardValueSet-meta.xml
+- SprintStatus.standardValueSet-meta.xml
+- AssessmentTaskCategory.standardValueSet-meta.xml
+- ActionPlanState.standardValueSet-meta.xml
+- GoalAssignmentStatus.standardValueSet-meta.xml
+
+## Step 2: Objects
+
+```bash
+sf project deploy start --source-dir .lsc-starter-config/LSStarterConfig/PackageComponents/objects --target-org <org>
+```
+
+Deploys objects and their sub-components (recordTypes, compactLayouts, fieldSets, webLinks, businessProcesses):
+- Account (recordTypes: Business, Business_Account, Health_Care_Organization; compactLayouts, fieldSets, webLinks)
+- BusinessLicense (fieldSets)
+- Case (recordTypes: Medical_Info_Request, Medical_Inquiry, Question; businessProcesses)
+- HealthcareProvider (recordTypes: Health_Care_Organization, Health_Care_Provider)
+- HealthcareProviderSpecialty (fieldSets)
+- Inquiry (recordTypes: Adverse_Event, LSC_General, Medical_Inquiry; compactLayouts, fieldSets)
+- InquiryQuestion (compactLayouts)
+- InquiryQuestionAnswer (compactLayouts, fieldSets)
+- PersonAccount (recordTypes: Health_Care_Provider, PersonAccount; compactLayouts)
+- Product2 (recordTypes: LSC_Marketing_Item, LSC_Sample)
+- ProviderAcctTerritoryInfo (recordTypes: Health_Care_Organization, Health_Care_Provider)
+- ProviderVisitProdDiscussion (recordTypes: Patient_Tracking, Product_Feedback)
+- User (fieldSets)
+- Visit (compactLayouts, fieldSets)
+
+## Step 3: Product Specification Types
+
+```bash
+sf project deploy start --source-dir .lsc-starter-config/LSStarterConfig/PackageComponents/productSpecificationTypes --target-org <org>
+```
+
+Files:
+- LSPromotionalItem.productSpecificationType-meta.xml
+- LSSampleProduct.productSpecificationType-meta.xml
+
+## Step 4: Product Specification Record Types
+
+```bash
+sf project deploy start --source-dir .lsc-starter-config/LSStarterConfig/PackageComponents/productSpecificationRecTypes --target-org <org>
+```
+
+Files:
+- LSC_Sample_LSSampleProduct.productSpecificationRecType-meta.xml
+- LS_MarketingItem_LSPromotionalItem.productSpecificationRecType-meta.xml
+
+## Step 5: Quick Actions
+
+```bash
+sf project deploy start --source-dir .lsc-starter-config/LSStarterConfig/PackageComponents/quickActions --target-org <org>
+```
+
+Files:
+- Account.LogAVisit.quickAction-meta.xml
+- Visit.Inquiry.quickAction-meta.xml
+
+## Step 6: LSC Custom Profile (Skeleton)
+
+```bash
+sf project deploy start --source-dir .lsc-starter-config/LSStarterConfig/PackageComponents/profiles/SkeletonProfile --target-org <org>
+```
+
+Deploys both skeleton profiles:
+- LSC Custom Profile.profile-meta.xml
+- Admin.profile-meta.xml
+
+These are minimal profiles with field permissions and application visibility. Layout assignments and flexipage overrides are added later in Steps 11 and 13.
+
+## Verifying Deployment Success
+
+After each deploy command, check the output. A successful deployment shows:
+```text
+Deploy Succeeded.
+```
+
+If deployment fails, the output shows:
+```text
+Deploy Failed.
+```
+
+Capture the error message and component name for the recovery flow.
+
+## Temporary Directory Pattern
+
+For selective deploys (layouts, flexipages), create a temp directory structure **inside the SFDX project** (a `.lsc-deploy-tmp/` under the project root — never `/tmp` or any path outside the project), then remove it when done:
+```bash
+mkdir -p .lsc-deploy-tmp/<metadata-type>
+cp <selected-files> .lsc-deploy-tmp/<metadata-type>/
+sf project deploy start --source-dir .lsc-deploy-tmp --target-org <org>
+rm -rf .lsc-deploy-tmp
+```
+
+Alternatively, use `--metadata` flag with specific component names:
+```bash
+sf project deploy start --metadata "Layout:Account-HCO Account Layout" --metadata "Layout:Visit-LSC Visit Layout" --target-org <org>
+```
+</content>