@salesforce/afv-skills 1.45.0 → 1.47.0

package/skills/life-sciences-kam-coordinate/references/stage-5-data-creation-data.md

@@ -0,0 +1,248 @@
+# KAM Data Creation — Field Reference
+
+> **Read the CSVs — do not treat these tables as authoritative.** The values below are a **snapshot** of one export of the `.lsc-starter-config/LSStarterConfig/Data/` CSV files, kept for orientation only. At execution time you MUST read the actual CSV for each object and use **only** the values it currently contains (one record per row). If a CSV differs from a table here — added/removed columns, changed values, extra rows — the **live CSV wins**. Never hardcode these values or reuse values from a previous run.
+>
+> **Do NOT narrate the difference to the user.** The example values here (e.g. `Immunexis 5mg`) are illustrative placeholders, not data — silently use whatever the live CSV contains and never tell the user that the live data differs from these examples, name a specific CSV row, or comment on the underlying data structure.
+
+Field values for all KAM records, sourced from `.lsc-starter-config/LSStarterConfig/Data/` CSV files (plus the explicit HCO account bundle). **All records are created as the ADMIN** (`--target-org <admin>`) — in the KAM workflow the end user does not exist yet (Stage 6), so there is no rep/admin split and no login-as-rep step.
+
+## Source folder & object→CSV mapping
+
+The CSVs come from <https://github.com/SalesforceLabs/LSStarterConfig.git>. As an embedded Stage 5, this stage is a pure consumer of `.lsc-starter-config/LSStarterConfig/` and MUST NOT download or delete it — the coordinator (`life-sciences-kam-coordinate`) owns the single download (start) and single delete (end). If the folder is absent when this stage runs, stop and report it must be provisioned by the coordinator.
+
+| Object | CSV file |
+|---|---|
+| Account | `account.csv` |
+| HealthcareProvider | `healthcareprovider.csv` |
+| ContactPointAddress | `contactpointaddress.csv` |
+| ObjectTerritory2Association | `objectterritory2association.csv` |
+| ProviderAcctTerritoryInfo | `provideracctterritoryinfo.csv` |
+| Product2 | `product2.csv` |
+| LifeSciMarketableProduct | `lifescimarketableproduct.csv` |
+| ProductTerritoryAvailability | `productterritoryavailability.csv` |
+
+> **No Visit chain.** The KAM workflow does NOT create `Visit`, `ProviderVisit`, `ProviderVisitProdDetailing`, or `ProviderVisitProdDiscussion`. Ignore those CSVs.
+
+## HCP Account (RecordType: Health_Care_Provider)
+
+This is the CSV-driven **person** account (an individual provider). The HCO (organization) account is a separate bundle below.
+
+| Field | Value | Source |
+|-------|-------|--------|
+| FirstName | Aaron | account.csv |
+| LastName | Morita | account.csv |
+| Salutation | Dr. | account.csv |
+| RecordType DeveloperName | Health_Care_Provider | account.csv |
+| IsActive | True | account.csv (standard `IsActive` boolean — NOT `IsActive__c`) |
+
+## HealthcareProvider
+
+| Field | Value | Source |
+|-------|-------|--------|
+| Name | Aaron Morita HP | healthcareprovider.csv |
+| IsActive | True | healthcareprovider.csv |
+| IsPrimaryProvider | True | healthcareprovider.csv |
+| ProviderType | Medical Doctor | healthcareprovider.csv |
+| Status | Active | healthcareprovider.csv |
+| AccountId | (from Account) | FK |
+
+> As admin you have FLS to all fields, so `NationalProviderIdentifier` and `IsSpeaker` may be set if the CSV lists them. If a create fails on a field, omit it and continue — those two are not required by any KAM downstream record.
+
+## ContactPointAddress
+
+| Field | Value | Source |
+|-------|-------|--------|
+| Name | 415 Mission St | contactpointaddress.csv |
+| AddressType | Billing | contactpointaddress.csv |
+| Street | 415 Mission St | contactpointaddress.csv |
+| City | San Francisco | contactpointaddress.csv |
+| State | California | contactpointaddress.csv |
+| StateCode | CA | contactpointaddress.csv |
+| PostalCode | 94105 | contactpointaddress.csv |
+| Country | United States | contactpointaddress.csv |
+| CountryCode | US | contactpointaddress.csv |
+| Latitude | 37.789853 | contactpointaddress.csv |
+| Longitude | -122.396806 | contactpointaddress.csv |
+| IsActive | True | contactpointaddress.csv |
+| IsPrimary | True | contactpointaddress.csv |
+| UsageType | Work | contactpointaddress.csv |
+| ParentId | (from HCP Account) | FK |
+
+## HCO Account bundle — Partners Healthcare (explicit values, NOT from CSV)
+
+In addition to the CSV-driven HCP account above, create a **Health Care Organization (HCO)** account and its provider and address. These three records use the **explicit values below** — they are **not** rows in any CSV (only the HCO ContactPointAddress reuses the CSV's address values). Both the Account and the HealthcareProvider use the **`Health_Care_Organization`** record type — look up each record type's Id by `DeveloperName` + `SobjectType` first (the DeveloperName is the same on both objects; the `SobjectType` differs):
+
+```bash
+# RecordTypeId for the HCO Account
+sf data query --query "SELECT Id FROM RecordType WHERE SobjectType='Account' AND DeveloperName='Health_Care_Organization'" --target-org <admin> --json
+# RecordTypeId for the HCO HealthcareProvider
+sf data query --query "SELECT Id FROM RecordType WHERE SobjectType='HealthcareProvider' AND DeveloperName='Health_Care_Organization'" --target-org <admin> --json
+```
+
+### HCO Account (RecordType: Health_Care_Organization)
+
+An **organization** account — use the `Name` field, not FirstName/LastName.
+
+| Field | Value | Source |
+|-------|-------|--------|
+| Name | Partners Healthcare | explicit |
+| IsActive | True | explicit |
+| RecordTypeId | Id of Account RecordType `Health_Care_Organization` | RecordType query above |
+
+```bash
+sf data create record --sobject Account --target-org <admin> \
+  --values "Name='Partners Healthcare' IsActive=true RecordTypeId=<hcoAccountRecordTypeId>" --json
+```
+
+Capture the returned **HCO Account Id** — the HCO HealthcareProvider (`AccountId`) and HCO ContactPointAddress (`ParentId`) both reference it.
+
+### HCO HealthcareProvider
+
+| Field | Value | Source |
+|-------|-------|--------|
+| Name | Partners Healthcare HP | explicit |
+| AccountId | (from HCO Account) | FK — the `Partners Healthcare` Account Id |
+| IsActive | True | explicit |
+| IsPrimaryProvider | True | explicit |
+| RecordTypeId | Id of HealthcareProvider RecordType `Health_Care_Organization` | RecordType query above |
+| Status | Active | explicit |
+
+```bash
+sf data create record --sobject HealthcareProvider --target-org <admin> \
+  --values "Name='Partners Healthcare HP' AccountId=<hcoAccountId> IsActive=true IsPrimaryProvider=true RecordTypeId=<hcoProviderRecordTypeId> Status=Active" --json
+```
+
+### HCO ContactPointAddress
+
+Reuse the **exact same address values from `contactpointaddress.csv`** used for the HCP ContactPointAddress above (Name, AddressType, Street, City, State, StateCode, PostalCode, Country, CountryCode, Latitude, Longitude, IsActive, IsPrimary, UsageType) — changing **only** the parent.
+
+| Field | Value | Source |
+|-------|-------|--------|
+| (all address fields) | same as the HCP `ContactPointAddress` (from `contactpointaddress.csv`) | contactpointaddress.csv |
+| ParentId | (from HCO Account `Partners Healthcare`) | FK — the HCO Account, **not** the HCP Account |
+
+```bash
+# Same --values as the HCP ContactPointAddress, with ParentId pointing at the HCO Account instead.
+sf data create record --sobject ContactPointAddress --target-org <admin> \
+  --values "<same address fields as the HCP ContactPointAddress> ParentId=<hcoAccountId>" --json
+```
+
+Capture the returned **HCO ContactPointAddress Id** — the HCO `ProviderAcctTerritoryInfo` references it as `PreferredAddressId`.
+
+### HCO ObjectTerritory2Association
+
+Same field values as the HCP `ObjectTerritory2Association` below, pointing at the HCO Account and the **same Stage-3 level-3 territory**.
+
+| Field | Value | Source |
+|-------|-------|--------|
+| ObjectId | (from HCO Account `Partners Healthcare`) | FK |
+| Territory2Id | (Stage-3 level-3 territory) | FK |
+| AssociationCause | Territory2Manual | objectterritory2association.csv |
+
+```bash
+sf data create record --sobject ObjectTerritory2Association --target-org <admin> \
+  --values "ObjectId=<hcoAccountId> Territory2Id=<territoryId> AssociationCause=Territory2Manual" --json
+```
+
+### HCO ProviderAcctTerritoryInfo
+
+Same field values as the HCP `ProviderAcctTerritoryInfo` below, pointing at the HCO Account, its ContactPointAddress, and the **same Stage-3 level-3 territory**.
+
+| Field | Value | Source |
+|-------|-------|--------|
+| AccountId | (from HCO Account `Partners Healthcare`) | FK |
+| Territory2Id | (Stage-3 level-3 territory) | FK |
+| PreferredAddressId | (from HCO ContactPointAddress) | FK |
+| IsActive | True | provideracctterritoryinfo.csv |
+| IsAvailableOffline | True | provideracctterritoryinfo.csv |
+| IsTargetedAccount | True | provideracctterritoryinfo.csv |
+| SourceType | Manual | provideracctterritoryinfo.csv |
+
+```bash
+sf data create record --sobject ProviderAcctTerritoryInfo --target-org <admin> \
+  --values "AccountId=<hcoAccountId> Territory2Id=<territoryId> PreferredAddressId=<hcoContactPointAddressId> IsActive=true IsAvailableOffline=true IsTargetedAccount=true SourceType=Manual" --json
+```
+
+## ObjectTerritory2Association
+
+| Field | Value | Source |
+|-------|-------|--------|
+| ObjectId | (from Account) | FK |
+| Territory2Id | (Stage-3 level-3 territory) | FK |
+| AssociationCause | Territory2Manual | objectterritory2association.csv |
+
+## ProviderAcctTerritoryInfo
+
+| Field | Value | Source |
+|-------|-------|--------|
+| AccountId | (from Account) | FK |
+| Territory2Id | (Stage-3 level-3 territory) | FK |
+| PreferredAddressId | (from ContactPointAddress) | FK |
+| IsActive | True | provideracctterritoryinfo.csv |
+| IsAvailableOffline | True | provideracctterritoryinfo.csv |
+| IsTargetedAccount | True | provideracctterritoryinfo.csv |
+| SourceType | Manual | provideracctterritoryinfo.csv |
+
+## Product2 (NO RecordType)
+
+| Field | Value | Source |
+|-------|-------|--------|
+| Name | Immunexis 5mg | product2.csv |
+| ProductCode | IM001-5 | product2.csv |
+| IsActive | True | product2.csv |
+
+> Do NOT set RecordTypeId — explicit requirement.
+
+## LifeSciMarketableProduct
+
+| Field | Value | Source |
+|-------|-------|--------|
+| Name | Immunexis 5mg | lifescimarketableproduct.csv |
+| ProductId | (from Product2) | FK |
+| IsActive | True | lifescimarketableproduct.csv |
+| IsAvlForSamplingAllocation | True | lifescimarketableproduct.csv |
+| Manufacturer | Makana Health | lifescimarketableproduct.csv |
+| DistributionMethod | Drop | lifescimarketableproduct.csv |
+| SignatureRequirementLevel | Mandatory | lifescimarketableproduct.csv |
+| SortOrder | 100 | lifescimarketableproduct.csv |
+| StartDate | 2026-07-01 | lifescimarketableproduct.csv |
+| Type | Product | lifescimarketableproduct.csv |
+
+> Capture the resulting `LifeSciMarketableProduct` Id — Part B (plan templates) of this stage references it as the `GoalDefinitionProduct.ProductId`.
+
+## ProductTerritoryAvailability
+
+| Field | Value | Source |
+|-------|-------|--------|
+| ProductId | (from LifeSciMarketableProduct) | FK |
+| TerritoryId | (Stage-3 level-3 territory) | FK |
+| AlignmentType | Territory Inclusion | productterritoryavailability.csv |
+| Purpose | Visit | productterritoryavailability.csv |
+| Status | Draft | productterritoryavailability.csv |
+| UsageType | LifeSciences | productterritoryavailability.csv |
+
+> The `TerritoryId` MUST be the same Stage-3 level-3 territory later assigned to the KAM user (Stage 6). Otherwise the KAM user sees no product/account data.
+
+---
+
+## Dependency Chain
+
+```text
+HCP Account (person, Health_Care_Provider)
+├── HealthcareProvider — AccountId
+├── ContactPointAddress — ParentId
+├── ObjectTerritory2Association — ObjectId, Territory2Id
+└── ProviderAcctTerritoryInfo — AccountId, PreferredAddressId (ContactPointAddress), Territory2Id
+
+HCO Account (organization, Health_Care_Organization — Partners Healthcare)
+├── HealthcareProvider (Partners Healthcare HP) — AccountId
+├── ContactPointAddress — ParentId (same CSV address values)
+├── ObjectTerritory2Association — ObjectId, Territory2Id
+└── ProviderAcctTerritoryInfo — AccountId, PreferredAddressId (HCO ContactPointAddress), Territory2Id
+
+Product2
+└── LifeSciMarketableProduct — ProductId
+    └── ProductTerritoryAvailability — ProductId, TerritoryId
+```
+
+Create in the order: HCP Account → HealthcareProvider → ContactPointAddress → ObjectTerritory2Association → ProviderAcctTerritoryInfo → HCO Account → HCO HealthcareProvider → HCO ContactPointAddress → HCO ObjectTerritory2Association → HCO ProviderAcctTerritoryInfo → Product2 → LifeSciMarketableProduct → ProductTerritoryAvailability.

package/skills/life-sciences-kam-coordinate/references/stage-6-ipad-validation-script.md

@@ -0,0 +1,35 @@
+# On-Device (iPad) Validation Script (KAM)
+
+Shown to the admin at the very end of the workflow — **after the mobile metadata cache reaches `Status='Active'`** (Stage 6 gate passed) and the final summary is displayed. Display the script **verbatim** to the admin so they can hand it to the KAM user, then **wait for the user to confirm** each step succeeded on the device. Once the user confirms, the setup is complete.
+
+The credentials in Step 1 are the KAM user created in Stage 6 (the user whose username contains `kam`). The account (`Partners Healthcare`), the objective/template (`Immunexis: Secure Q3 Formulary Position`), and its Assessment Tasks are the records created in Stage 5 — present them exactly as named below.
+
+## Script (display verbatim)
+
+```markdown
+Here are the refined steps to validate on the Life Sciences Mobile Application (iPad).
+
+Step 1 — Log in to the Life Sciences Mobile Application
+Open the application on your iPad, enter your credentials, and verify that the home screen loads successfully.
+
+Step 2 — Create a new Account Plan
+Tap Account Plan in the top navigation bar, then tap New.
+Enter an Account Plan Name.
+Search for and select your target account (for example, Partners Healthcare).
+Fill out the SWOT Analysis, Customer Landscape, and Competitive Landscape sections as needed.
+Tap Save. You should now see your newly created Account Plan.
+
+Step 3 — Import an objective template
+Navigate to the Account Plan Objectives tab and tap Import Template.
+Locate the template you want to use (such as Immunexis: Secure Q3 Formulary Position) and tap to expand the hierarchy.
+Tap Select All, then tap Next.
+Review your selections and tap Import.
+The assessment tasks from the template will now appear under your Action Plan.
+
+Step 4 — Complete a task and sync your data
+Tap to edit any of your new tasks, change the status to Completed, and tap Done.
+Once you are finished updating tasks, initiate a data sync on your device.
+Note: Because your data calculates securely on the server, the progress bar on your Action Plan won't move the exact instant you tap "Completed." It will advance as soon as your sync finishes.
+```
+
+Once the user confirms, this is the end of the setup.

package/skills/life-sciences-kam-coordinate/references/stage-6-metadata-cache-generation.md

@@ -0,0 +1,155 @@
+# Metadata Cache Generation Reference
+
+Detailed commands for the metadata-cache generation steps of Stage 6 (KAM User Provisioning). Run entirely as the **admin** (`--target-org <admin>`).
+
+> **No permission set required.** The generate Connect API bypasses metadata
+> validation itself, so the previously-documented `SkipMetadataValidation`
+> permission set (`PermissionsSkipVldBefMetadataGeneration` /
+> `PermissionsGenerateLifeSciencesMetadata`) is NOT needed. Verified empirically:
+> generation enqueues and the async job runs with no such permission set assigned.
+
+> **Parent-link field:** the parent-link field on `LifeSciMobileMetadataRecord` is
+> `ParentMobileMetadataRecId` (used below). If you need to confirm the schema on your
+> org, describe the object:
+>
+> ```bash
+> sf sobject describe --sobject LifeSciMobileMetadataRecord --target-org <admin> --json \
+>   | grep -o '"name":"[^"]*"'
+> ```
+
+## Step A: Create LifeSciMobileMetadataRecord Prerequisite
+
+Create a **parent** record and a **child** record linked to the LSC Custom Profile.
+Set **both** records to `ValidationCompleted` — the generate API in Step B rejects the
+call unless the **parent** record's `Status` is `ValidationCompleted` (not just the
+child's). The generate API is called with the **parent** record ID.
+
+Run as admin (`--target-org <admin>`):
+
+```bash
+sf apex run --target-org <admin> --json <<'EOF'
+// Create parent record.
+LifeSciMobileMetadataRecord parent = new LifeSciMobileMetadataRecord(
+    IntegrationStatus = 'New',
+    Status = 'New'
+);
+insert parent;
+
+// Create child record for the LSC Custom Profile.
+Profile pf = [SELECT Id FROM Profile WHERE Name = 'LSC Custom Profile'];
+LifeSciMobileMetadataRecord child = new LifeSciMobileMetadataRecord(
+    ParentMobileMetadataRecId = parent.Id,
+    ProfileId = pf.Id,
+    IntegrationStatus = 'New',
+    Status = 'New'
+);
+insert child;
+
+// Set BOTH parent and child to ValidationCompleted (the API requires the parent).
+child.Status = 'ValidationCompleted';
+update child;
+parent.Status = 'ValidationCompleted';
+update parent;
+
+System.debug('Parent Id: ' + parent.Id);
+System.debug('Child Id: ' + child.Id);
+EOF
+```
+
+Extract the **parent record ID** from the debug log output — it is required as the `parentMetadataRecordId` in Step B.
+
+---
+
+## Step B: Call the Metadata Generate Connect API
+
+Use the CLI's own authenticated REST client (`sf api request rest`) — it builds the
+`Authorization` header correctly. A hand-rolled `curl` with the token from
+`sf org display` fails with `INVALID_AUTH_HEADER` (401), even though the same token
+works for CLI data queries — do NOT use raw curl for this endpoint.
+
+### Build the request body
+
+The body accepts `parentMetadataRecordId`, `apiVersion`, and `prefix`. Use `apiVersion`
+`65.0` (verified working). Do NOT include `generateStandardTranslations` — the endpoint
+rejects it with `JSON_PARSER_ERROR: Unrecognized field "generateStandardTranslations"`.
+
+Write the body to a **project-local** relative file (never `/tmp` or any path outside the project); remove it after the call below:
+
+```bash
+cat > .lsc-mdgen-body.json <<'EOF'
+{
+  "parentMetadataRecordId": "<parentRecordId>",
+  "apiVersion": "65.0",
+  "prefix": "lsc4ce"
+}
+EOF
+```
+
+### Call the endpoint
+
+Match the endpoint's `vXX.0` to the `apiVersion` in the body. Pass the body file with a
+leading `@` (a bare path is sent as a literal string and triggers `JSON_PARSER_ERROR`):
+
+```bash
+sf api request rest \
+  "/services/data/v65.0/connect/life-sciences/commercial/metadata/actions/generate" \
+  --method POST \
+  --body @.lsc-mdgen-body.json \
+  --target-org <admin>
+rm -f .lsc-mdgen-body.json
+```
+
+### Expected response
+
+Success is a JSON message (HTTP 200), not 202:
+
+```json
+{ "message": "Task enqueued for metadata cache generation." }
+```
+
+Generation then runs asynchronously.
+
+### Verify completion
+
+Query both the parent and its child records (use your org's parent-link field name):
+
+```bash
+sf data query --query "SELECT Id, Status, IntegrationStatus, IntegrationErrorMessage, MetadataDocumentId, LastModifiedDate FROM LifeSciMobileMetadataRecord WHERE Id='<parentRecordId>' OR ParentMobileMetadataRecId='<parentRecordId>'" --target-org <admin> --json
+```
+
+The records move through intermediate states (`New → InProgress → Loading → Processing`)
+and then transition to `Status='Active'`. **`Active` is the success state** — it means the
+cache was generated; the child record's `MetadataDocumentId` is populated with the generated
+document Id. The enqueue message only confirms the task was accepted; keep polling the query
+above until `Status='Active'` before treating generation as complete.
+
+> **How to report progress while polling.** The async job can take several minutes; that is
+> normal. As long as the records are advancing through the intermediate states, simply tell
+> the user the generation **is progressing and you are polling for it to become `Active`** —
+> then poll again. Do NOT frame it as a timeout, a missed deadline, or "it didn't complete
+> within the N-minute window" — there is no fixed window, and that phrasing wrongly implies
+> something is wrong when the job is running normally. Only surface a problem if the records
+> go to `Inactive` or stop advancing entirely (see below).
+
+A transition to `Inactive` (or a record that stays unchanged with an unchanged
+`LastModifiedDate`) is **not** success — the async job ran but produced no cache, or
+never ran. Check Setup → Apex Jobs for the failed generation job and its error, and
+inspect the record's `IntegrationStatus` / `IntegrationErrorMessage` fields for detail.
+
+---
+
+## Error handling
+
+| Error | Resolution |
+|-------|------------|
+| `LifeSciMobileMetadataRecord` sObject not found | LSC packages not installed or API < v65.0 |
+| `Field does not exist: ParentMobileMetadataRecId` (or similar) on compile | Describe the object to confirm the parent-link field name on your org and use the reported name |
+| `INVALID_AUTH_HEADER` (401) from Connect API | You used raw `curl` — switch to `sf api request rest`, which builds the auth header correctly |
+| `JSON_PARSER_ERROR: Unrecognized field "generateStandardTranslations"` | Remove that field from the body — only `parentMetadataRecordId`, `apiVersion`, and `prefix` are accepted |
+| `JSON_PARSER_ERROR: Unexpected character ('/')` | `--body` got a literal path — prefix the file with `@` (`--body @.lsc-mdgen-body.json`) |
+| `Profile 'LSC Custom Profile' not found` | Run Stage 2 (Starter Config Deploy) first — the child record needs the profile Id |
+| `...isn't ValidationCompleted` from Connect API | Set the **parent** record's `Status` to `ValidationCompleted` (the API requires the parent, not just the child), then retry |
+| HTTP 400 from Connect API | Check: parentMetadataRecordId valid, parent Status='ValidationCompleted', prefix='lsc4ce' |
+| HTTP 404 from Connect API | Endpoint not available — verify API version v65.0+ and LSC packages |
+| Records never leave their status (LastModifiedDate unchanged) | Async job didn't run — wait 30s; check Setup → Apex Jobs for failures |
+| Records go to `Inactive` instead of `Active` | Generation ran but produced no cache — this is a failure, not success. Check Setup → Apex Jobs and the record's `IntegrationErrorMessage` for the cause |

package/skills/life-sciences-kam-coordinate/references/stage-6-user-provisioning-details.md

@@ -0,0 +1,146 @@
+# KAM User Provisioning Details
+
+## Required Permission Sets
+
+The KAM user gets **exactly four** permission sets:
+
+| Permission Set Label | Expected API Name | Purpose |
+|---------------------|-------------------|---------|
+| Health Cloud Starter | HealthCloudStarter | Health Cloud foundation permissions |
+| Life Sciences Key Account Management | LifeSciencesKeyAccountManager | Key account management permissions |
+| Life Sciences Field Sales Representative | LifeSciencesFieldSalesRepresentative | Life Sciences field sales rep permissions |
+| Life Sciences Core | LifeSciencesCore | Life Sciences core platform permissions |
+
+> **Resolve by label, not API name.** The API names above are the expected values; managed-package sets may be namespace-prefixed. Always confirm the actual `Name` via the label query below before assigning.
+
+### Querying Permission Sets
+
+Permission sets from managed packages may have namespace-prefixed API names. If the standard names don't return results, try:
+
+```bash
+sf data query --query "SELECT Id, Name, NamespacePrefix, Label FROM PermissionSet WHERE Label LIKE '%Key Account%' OR Label LIKE '%Health Cloud%' OR Label LIKE '%Field Sales%' OR Label LIKE '%Life Sciences Core%'" --target-org <org> --json
+```
+
+---
+
+## Required User Fields
+
+When creating a user via `sf data create record`, these fields are mandatory:
+
+| Field | Description | Default Value | Admin can edit? |
+|-------|-------------|---------------|-----------------|
+| `FirstName` | User's first name | `Jordan` | Yes |
+| `LastName` | User's last name | `Lee` | Yes |
+| `Email` | User's email address | `jordan.lee@<orgdomain>` | Yes |
+| `Username` | Globally unique username — **must contain the text `kam`** | `jordan.lee.kam@<orgdomain>` (auto-generated) | No — auto |
+| `Alias` | Max 8 characters | `jlee` — first initial + last name (truncated) | No — auto |
+| `ProfileId` | 18-char record ID | `LSC Custom Profile` (queried from org) | No — fixed |
+| `IsActive` | Must be `true` | `true` | No — fixed |
+| `TimeZoneSidKey` | User's timezone | `America/Los_Angeles` | No — default |
+| `LocaleSidKey` | User's locale | `en_US` | No — default |
+| `EmailEncodingKey` | Email encoding | `UTF-8` | No — default |
+| `LanguageLocaleKey` | Language | `en_US` | No — default |
+
+> **Username must contain `kam`.** The KAM spec requires the text `kam` in the username (e.g. `jordan.lee.kam@<orgdomain>`). The username is **auto-generated** from the (possibly edited) name — never asked for. If the derived form lacks `kam`, insert a `.kam` segment.
+
+## Default User Details & Confirmation (show BEFORE creating)
+
+Before creating the user, present the default/derived details above as a table to the admin and get explicit confirmation. **The admin may edit `FirstName`, `LastName`, and `Email` only.** The `Username` and `Alias` are **auto-generated** (never asked for); the remaining fields are fixed defaults. If the admin edits the name, **re-derive the `Username` and `Alias` and re-display** before proceeding. **Do NOT create the user until the admin confirms** — this is the only user-detail confirmation in Stage 6 (permsets, territory, and password proceed automatically per the stage rules).
+
+Example prompt: *"Before I create the KAM user, here are the details — First name **Jordan**, Last name **Lee**, Email **jordan.lee@\<orgdomain\>**. I'll auto-generate the username as **jordan.lee.kam@\<orgdomain\>** (Active, on LSC Custom Profile, en_US / America/Los_Angeles). Change the first/last name or email, or shall I create it as-is?"*
+
+- **Username auto-generation:** derive from the (possibly edited) name as `<first>.<last>.kam@<orgdomain>` (lowercased); it MUST contain `kam`. `<orgdomain>` keeps it globally unique. On `DUPLICATE_USERNAME`, append a unique suffix while preserving `kam` (e.g. `.kam.dev`).
+- **Alias auto-generation:** first initial + last name, truncated to 8 characters (e.g. `Jordan Lee` → `jlee`).
+
+### Optional Fields
+
+| Field | Description |
+|-------|-------------|
+| `Title` | Job title (e.g., "KAM User") |
+| `Department` | Department name |
+| `Phone` / `MobilePhone` | Phone numbers |
+
+---
+
+## Territory Assignment
+
+### UserTerritory2Association Fields
+
+| Field | Description |
+|-------|-------------|
+| `UserId` | 18-char User record ID |
+| `Territory2Id` | 18-char Territory2 record ID — **the same Stage-3 level-3 territory used for ProductTerritoryAvailability in Stage 5** |
+| `RoleInTerritory2` | Optional — leave blank unless the user specifies |
+
+### Identifying the Level-3 Territory
+
+The level-3 territory is the leaf node in the 3-level hierarchy created (or reused) by `life-sciences-territory-configure` in Stage 3. The coordinator captured its ID in `OrchestrationState.territoryId`. **Use that exact territory** — it MUST match the territory used for `ProductTerritoryAvailability` in Stage 5, or the KAM user sees no product/account data. Query to confirm:
+
+```bash
+sf data query --query "SELECT Id, Name, DeveloperName, ParentTerritory2.Name, ParentTerritory2.ParentTerritory2.Name FROM Territory2 WHERE ParentTerritory2.ParentTerritory2Id != null AND Territory2Model.State = 'Active'" --target-org <org> --json
+```
+
+Both the KAM user **and** the admin are assigned to this same leaf territory.
+
+---
+
+## Error Handling
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `DUPLICATE_USERNAME` | Username exists in another org | Append a unique suffix while keeping `kam` (e.g., `.kam.dev`) |
+| `DUPLICATE_VALUE` on PermissionSetAssignment | Permission set already assigned | Skip — not an error |
+| `DUPLICATE_VALUE` on UserTerritory2Association | User already assigned to territory | Skip — not an error |
+| `INVALID_CROSS_REFERENCE_KEY` on ProfileId | Profile ID wrong or from a different org | Re-query the profile ID |
+| `FIELD_INTEGRITY_EXCEPTION` on Username | Username format invalid | Must be email-like format (contains `@`) |
+| `REQUIRED_FIELD_MISSING` | A mandatory field was omitted | Check all required fields are provided |
+
+---
+
+## Setting the User's Password
+
+A user created via `sf data create record` has **no password and receives no email** — they cannot log in until a password is set. Set one with anonymous Apex, writing the temp file to a **project-local** relative path (never `/tmp` or any path outside the project) and removing it right after:
+
+```bash
+echo "System.setPassword('<newUserId>', '<password>');" > .lsc-setpw.apex
+sf apex run --file .lsc-setpw.apex --target-org <org> --json
+rm -f .lsc-setpw.apex
+```
+
+Confirm `compiled: true` and `success: true`. The password must meet the org's policy (default: ≥8 chars, mixed case, at least one number and one symbol). The user is prompted to change it on first login.
+
+**Do not use `sf org generate password --on-behalf-of <username>`** — it only works for users with a local CLI auth entry (e.g. created via `sf org create user`) and fails for API-created users with `NamedOrgNotFoundError`. Alternatively, an admin can reset the password from Setup → Users → <user> → Reset Password to email a set-password link.
+
+Get the login URL for the credential handoff:
+
+```bash
+sf org display --target-org <org> --json    # use the instanceUrl field
+```
+
+---
+
+## Verification Queries
+
+### Verify user was created correctly
+
+```bash
+sf data query --query "SELECT Id, Name, Username, Profile.Name, IsActive FROM User WHERE Username = '<username>'" --target-org <org> --json
+```
+
+### Verify permission set assignments (hard count = 4)
+
+Filter out the profile-owned permission set (`IsOwnedByProfile = false`) so the result matches the 4 sets you assigned rather than a hidden profile-owned row:
+
+```bash
+sf data query --query "SELECT PermissionSet.Label, PermissionSet.Name FROM PermissionSetAssignment WHERE AssigneeId = '<userId>' AND PermissionSet.IsOwnedByProfile = false" --target-org <org> --json
+```
+
+This MUST return **exactly 4 rows**: `{HealthCloudStarter, LifeSciencesKeyAccountManager, LifeSciencesFieldSalesRepresentative, LifeSciencesCore}`.
+
+### Verify territory assignments
+
+```bash
+sf data query --query "SELECT User.Name, User.Username, Territory2.Name, Territory2.DeveloperName FROM UserTerritory2Association WHERE Territory2Id = '<territoryId>'" --target-org <org> --json
+```
+
+Expect at least 2 rows (the KAM user + the admin).