@salesforce/afv-skills 1.31.0 → 1.32.0

package/skills/sales-agentforce-pipeline-management-configure/references/metadata-inventory.md

@@ -0,0 +1,330 @@
+# Pipeline Management Metadata Inventory
+
+Complete inventory of all metadata components auto-provisioned by Pipeline Management. Use this as a reference for org inspection, troubleshooting, and metadata migration.
+
+---
+
+## Metadata Types and Components
+
+### 1. Settings
+
+| Metadata Type | Full Name | Key Fields | API | Notes |
+|--------------|-----------|-----------|-----|-------|
+| `SalesDealAgentSettings` | `SalesDealAgent` | `enableDealAgent`, `enableDealAgentAutoApproveAllTasks` | SOAP v64.0+ only | CLI returns 'Settings type is unknown' |
+| `EinsteinGptSettings` | `EinsteinGpt` | `enableGptAnswerGenerationForKbArticles` | SOAP v62.0+ or CLI | Required prerequisite |
+| `EinsteinCopilotSettings` | `EinsteinCopilot` | `enableAgentLiveSuggestionsInTab` | SOAP v62.0+ or CLI | Required prerequisite |
+| `EnhancedNotesSettings` | `EnhancedNotes` | `enableEnhancedNotes` | CLI retrieve+deploy | Prerequisite for note ingestion |
+| `EmailAdministrationSettings` | `EmailAdministration` | `enableInternalNotesInEmailSnippet` | CLI retrieve+deploy | Prerequisite for email ingestion |
+| `OpportunitySettings` | `Opportunity` | `enableFindSimilarOpportunities` | CLI retrieve+deploy | Prerequisite for grounding data |
+
+**Retrieval**:
+```bash
+sf project retrieve start --metadata "Settings:SalesDealAgentSettings" --target-org $ORG 2>/dev/null
+sf project retrieve start --metadata "Settings:EinsteinGptSettings" --target-org $ORG 2>/dev/null
+sf project retrieve start --metadata "Settings:EinsteinCopilotSettings" --target-org $ORG 2>/dev/null
+sf project retrieve start --metadata "Settings:EnhancedNotesSettings" --target-org $ORG 2>/dev/null
+sf project retrieve start --metadata "Settings:EmailAdministrationSettings" --target-org $ORG 2>/dev/null
+sf project retrieve start --metadata "Settings:OpportunitySettings" --target-org $ORG 2>/dev/null
+```
+
+---
+
+### 2. Permission Set Groups
+
+| Developer Name | API Name | Purpose | Auto-Assigned To |
+|----------------|----------|---------|------------------|
+| `SalesManagementUserPsg` | `SalesManagementUserPsg` | Grants end users access to Pipeline Management features | Sales users (manual assignment required) |
+| `SalesManagementAgentUserPsg` | `SalesManagementAgentUserPsg` | Grants agent system user access to opportunity data | Agent user (auto-assigned on creation) |
+
+**SOQL Query**:
+```bash
+sf data query -q "SELECT Id, DeveloperName, MasterLabel FROM PermissionSetGroup WHERE DeveloperName LIKE 'SalesManagement%'" --target-org $ORG --json 2>/dev/null
+```
+
+**Contained Permission Sets** (in `SalesManagementAgentUserPsg`):
+- `PipelineManagementAgentAutonomousUser` — Allows autonomous field updates
+- `PipelineManagementAgentBase` — Base permissions for agent operations
+- (Other permission sets may vary by org edition/license)
+
+---
+
+### 3. Bot (Agent)
+
+| Developer Name | Label | Type | Status | Template |
+|----------------|-------|------|--------|----------|
+| `SalesAgent` | `Sales Management Agent` | Agentforce | Active/Draft | `SalesMgmt__SalesAgent` |
+
+**SOQL Query** (standard SOQL — BotDefinition has no `Label` or `Status` column, and is not supported by the Tooling API):
+```bash
+sf data query -q "SELECT Id, DeveloperName, Description FROM BotDefinition WHERE DeveloperName = 'SalesAgent'" --target-org $ORG --json 2>/dev/null
+```
+
+**Retrieval**:
+```bash
+sf project retrieve start --metadata "Bot:SalesAgent" --target-org $ORG 2>/dev/null
+```
+
+**Components**:
+- Bot metadata file: `force-app/main/default/bots/SalesAgent.bot-meta.xml`
+- Bot versions (auto-versioned on publish)
+
+---
+
+### 4. BotVersion
+
+Active bot version(s) for `SalesAgent`. Multiple versions may exist (draft, published, active).
+
+**SOQL Query** (standard SOQL — `BotVersion`, like `BotDefinition`, is NOT supported by the Tooling API):
+```bash
+sf data query -q "SELECT Id, BotDefinition.DeveloperName, VersionNumber, Status FROM BotVersion WHERE BotDefinition.DeveloperName = 'SalesAgent' ORDER BY VersionNumber DESC" --target-org $ORG --json 2>/dev/null
+```
+
+---
+
+### 5. Flows
+
+| API Name | Label | Type | Template | Purpose |
+|----------|-------|------|----------|---------|
+| `sales_pipe_mgmt__OppSuggGenSchFlow` | `Opportunity Suggestion Generation Scheduled Flow` | Scheduled-Triggered | **Yes** (do not activate directly) | Template flow for suggestion processing |
+| `Process_Field_Update_Suggestions` | `Process Field Update Suggestions` | Scheduled-Triggered | No (cloned from template) | Active flow that processes suggestions |
+| `sales_pipe_mgmt__GetOppGroundingData` | `Get Opportunity Grounding Data` | Invocable | No | Retrieves notes, emails, calls for grounding |
+| `sales_pipe_mgmt__GetRcmdConvTscp` | `Get Recommended Conversation Transcript` | Invocable | No | Retrieves conversation transcripts |
+
+**SOQL Queries** — use `FlowDefinitionView` (data API). `FlowDefinition` is a **metadata**
+type, not a data-API sObject (`sObject type 'FlowDefinition' is not supported`, and
+`--use-tooling-api` does NOT fix it — it lives in the Metadata API); `FlowDefinitionView`
+is the queryable view, uses `IsActive` (not `Status`), and is what the live scripts use:
+```bash
+# Check all Pipeline Management flows
+sf data query -q "SELECT ApiName, Label, ProcessType, IsActive, IsTemplate FROM FlowDefinitionView WHERE ApiName LIKE '%sales_pipe_mgmt%' OR ApiName LIKE '%Field_Update_Suggestions%'" --target-org $ORG --json 2>/dev/null
+
+# Check if template flow exists
+sf data query -q "SELECT ApiName, IsTemplate FROM FlowDefinitionView WHERE ApiName = 'sales_pipe_mgmt__OppSuggGenSchFlow'" --target-org $ORG --json 2>/dev/null
+
+# Check cloned flow — query by ApiName. A Metadata-API deploy of the template does NOT
+# populate FlowDefinitionView.SourceTemplateId (org-verified), so detect by name;
+# SourceTemplateId is populated only for Setup-UI "Save As" clones.
+sf data query -q "SELECT Id, ApiName, Label, IsActive, SourceTemplateId FROM FlowDefinitionView WHERE ApiName = 'Process_Field_Update_Suggestions' AND IsTemplate = false" --target-org $ORG --json 2>/dev/null
+```
+
+**Retrieval**:
+```bash
+sf project retrieve start --metadata "Flow:sales_pipe_mgmt__OppSuggGenSchFlow" --target-org $ORG 2>/dev/null
+sf project retrieve start --metadata "Flow:Process_Field_Update_Suggestions" --target-org $ORG 2>/dev/null
+sf project retrieve start --metadata "Flow:sales_pipe_mgmt__GetOppGroundingData" --target-org $ORG 2>/dev/null
+sf project retrieve start --metadata "Flow:sales_pipe_mgmt__GetRcmdConvTscp" --target-org $ORG 2>/dev/null
+```
+
+---
+
+### 6. GenAiPromptTemplate
+
+| Developer Name | Label | Type | Purpose |
+|----------------|-------|------|---------|
+| `sales_pipe_mgmt__RecommendStageforOpp` | `Recommend Stage for Opportunity` | Prompt Template | Generates stage recommendations |
+| `sales_pipe_mgmt__RecommendNextStepforOpp` | `Recommend Next Step for Opportunity` | Prompt Template | Generates next step suggestions |
+
+**Discovery** — `GenAiPromptTemplate` is **not SOQL-queryable** (Tooling or standard both return "sObject type 'GenAiPromptTemplate' is not supported"). Use the REST discovery endpoint instead:
+```bash
+sf api request rest "/services/data/v64.0/einstein/prompt-templates" --target-org $ORG 2>/dev/null \
+  | jq -r '.promptRecords[]? | select(.fields.DeveloperName.value | test("sales_pipe_mgmt")) | "\(.fields.DeveloperName.value)  active=\(.fields.IsActive.value)"'
+```
+
+**Retrieval**:
+```bash
+sf project retrieve start --metadata "GenAiPromptTemplate:sales_pipe_mgmt__RecommendStageforOpp" --target-org $ORG 2>/dev/null
+sf project retrieve start --metadata "GenAiPromptTemplate:sales_pipe_mgmt__RecommendNextStepforOpp" --target-org $ORG 2>/dev/null
+```
+
+---
+
+### 7. Agent User
+
+| Field | Value |
+|-------|-------|
+| **Username pattern** | `salesmanagementagentuser@<uuid>.<org-domain>.ext` |
+| **Profile** | `System Administrator` or dedicated agent profile |
+| **IsActive** | `true` |
+| **UserType** | `CspLitePortal` or similar agent-specific type |
+
+**SOQL Query**:
+```bash
+sf data query -q "SELECT Id, Username, Name, Profile.Name, IsActive, UserType FROM User WHERE Username LIKE '%salesmanagementagentuser%'" --target-org $ORG --json 2>/dev/null
+```
+
+**Permission Set Group Assignment**:
+```bash
+# Get agent user ID
+AGENT_USER_ID=$(sf data query -q "SELECT Id FROM User WHERE Username LIKE '%salesmanagementagentuser%'" --target-org $ORG --json 2>/dev/null | jq -r '.result.records[0].Id')
+
+# Check PSG assignment
+sf data query -q "SELECT AssigneeId, PermissionSetGroup.DeveloperName FROM PermissionSetAssignment WHERE AssigneeId = '${AGENT_USER_ID}' AND PermissionSetGroup.DeveloperName = 'SalesManagementAgentUserPsg'" --target-org $ORG --json 2>/dev/null
+```
+
+---
+
+### 8. Setup Entities & Standard Objects
+
+#### OpptStageDescription (Opportunity Stage Descriptions)
+
+`OpptStageDescription` is a **Tooling-API setup entity** — NOT a `__c` custom object. It has no
+`Stage__c`/`Description__c` fields and is not accessible via `sf sobject describe` or the plain data
+API. It appears in `EntityDefinition`, is queryable **only with `--use-tooling-api`**, and is
+auto-provisioned when Pipeline Management is enabled (test orgs show pre-populated MEDDIC rows).
+Field names verified on a live org (`pm-new-org`).
+
+| Purpose | Key fields (Tooling) | API Name | Access |
+|---------|----------------------|----------|--------|
+| Stores stage-to-description mappings for stage-suggestion grounding | `OpportunityStageApiName` (the stage picklist value), `Description`, `MasterLabel`, `DeveloperName` | `OpptStageDescription` (no `__c`) | Tooling API only |
+
+> **Note:** `OpptStageDescription` has **no `OpportunityRecordTypeId` column** — descriptions are global-per-stage, keyed only by `OpportunityStageApiName`. A single description record applies across all Opportunity record types that expose that stage. (W-23356857)
+
+**SOQL Query** (Tooling API):
+```bash
+sf data query -q "SELECT Id, OpportunityStageApiName, Description FROM OpptStageDescription" --target-org $ORG --use-tooling-api --json 2>/dev/null
+```
+
+`setup-all.sh` creates/updates these rows via `sf data create/update record --sobject OpptStageDescription`
+(Tooling-backed); see the stage-description handling in `scripts/shared/stage-descriptions.sh`
+(`run_stage_descriptions`), invoked from setup-all.sh Phase 4c.5 — BEFORE the StageName
+prompt is deployed/tested, since the descriptions are that prompt's grounding.
+
+#### AiGenActionItem (Field Update Suggestions)
+
+`AiGenActionItem` is the **standard** object (no `__c` suffix) where Pipeline Management stores every field-update suggestion. There is **no** `FieldCompletion` / `FieldCompletion__c` object — that name does not exist on any org; do not query it.
+
+| Purpose | Key fields (all standard) | API Name |
+|---------|---------------------------|----------|
+| Stores field-update suggestions (pending/applied/expired) | `ParentId` (= the Opportunity Id, filterable), `Subject` (= the field API name, e.g. `Risk__c`), `Type` (`FIELD_UPDATE`), `Status` (`WAITING`/`EXPIRED`), `SuggestedNewValue` (textarea), `AgentType` (`SALES_MANAGEMENT_AGENT`) | `AiGenActionItem` |
+
+**SOQL Query** (filter by Opportunity via `ParentId`; `SuggestedNewValue` is not filterable):
+```bash
+sf data query -q "SELECT Id, ParentId, Subject, Type, Status, SuggestedNewValue FROM AiGenActionItem WHERE Type = 'FIELD_UPDATE' AND ParentId = '<oppId>' ORDER BY CreatedDate DESC LIMIT 10" --target-org $ORG --json 2>/dev/null
+```
+
+---
+
+### 9. Apex Classes (if present)
+
+Pipeline Management may deploy supporting Apex classes for:
+- Custom grounding data retrieval
+- Stage transition validation
+- Suggestion filtering logic
+
+**Check for Apex**:
+```bash
+sf data query -q "SELECT Id, Name FROM ApexClass WHERE Name LIKE '%SalesPipeMgmt%' OR Name LIKE '%DealAgent%'" --target-org $ORG --use-tooling-api --json 2>/dev/null
+```
+
+---
+
+## Metadata Dependency Graph
+
+```text
+SalesDealAgentSettings (root)
+├── EinsteinGptSettings (required)
+│   └── EinsteinCopilotSettings (required)
+├── EnhancedNotesSettings (recommended)
+├── EmailAdministrationSettings (recommended)
+├── OpportunitySettings (recommended)
+├── BotDefinition: SalesAgent
+│   ├── Agent User (salesmanagementagentuser@...)
+│   │   └── PermissionSetGroup: SalesManagementAgentUserPsg
+│   ├── Flows
+│   │   ├── sales_pipe_mgmt__OppSuggGenSchFlow (template)
+│   │   ├── Process_Field_Update_Suggestions (active)
+│   │   ├── sales_pipe_mgmt__GetOppGroundingData
+│   │   └── sales_pipe_mgmt__GetRcmdConvTscp
+│   ├── GenAiPromptTemplates
+│   │   ├── sales_pipe_mgmt__RecommendStageforOpp
+│   │   └── sales_pipe_mgmt__RecommendNextStepforOpp
+│   ├── Setup Entities (Tooling API)
+│   │   └── OpptStageDescription (OpportunityStageApiName, Description) ← global-per-stage, no RT column
+│   └── Standard Objects
+│       └── AiGenActionItem (field-update suggestions)
+└── PermissionSetGroup: SalesManagementUserPsg (assigned to end users)
+```
+
+---
+
+## Metadata Retrieval Script
+
+Complete script to retrieve all Pipeline Management metadata:
+
+```bash
+#!/bin/bash
+ORG="pipeline-mgmt-org"
+
+echo "Retrieving Pipeline Management metadata..."
+
+# Settings
+sf project retrieve start --metadata "Settings:SalesDealAgentSettings" --target-org $ORG 2>/dev/null
+sf project retrieve start --metadata "Settings:EinsteinGptSettings" --target-org $ORG 2>/dev/null
+sf project retrieve start --metadata "Settings:EinsteinCopilotSettings" --target-org $ORG 2>/dev/null
+sf project retrieve start --metadata "Settings:EnhancedNotesSettings" --target-org $ORG 2>/dev/null
+sf project retrieve start --metadata "Settings:EmailAdministrationSettings" --target-org $ORG 2>/dev/null
+sf project retrieve start --metadata "Settings:OpportunitySettings" --target-org $ORG 2>/dev/null
+
+# Permission Set Groups
+sf project retrieve start --metadata "PermissionSetGroup:SalesManagementUserPsg" --target-org $ORG 2>/dev/null
+sf project retrieve start --metadata "PermissionSetGroup:SalesManagementAgentUserPsg" --target-org $ORG 2>/dev/null
+
+# Bot
+sf project retrieve start --metadata "Bot:SalesAgent" --target-org $ORG 2>/dev/null
+
+# Flows
+sf project retrieve start --metadata "Flow:sales_pipe_mgmt__OppSuggGenSchFlow" --target-org $ORG 2>/dev/null
+sf project retrieve start --metadata "Flow:Process_Field_Update_Suggestions" --target-org $ORG 2>/dev/null
+sf project retrieve start --metadata "Flow:sales_pipe_mgmt__GetOppGroundingData" --target-org $ORG 2>/dev/null
+sf project retrieve start --metadata "Flow:sales_pipe_mgmt__GetRcmdConvTscp" --target-org $ORG 2>/dev/null
+
+# Prompt Templates
+sf project retrieve start --metadata "GenAiPromptTemplate:sales_pipe_mgmt__RecommendStageforOpp" --target-org $ORG 2>/dev/null
+sf project retrieve start --metadata "GenAiPromptTemplate:sales_pipe_mgmt__RecommendNextStepforOpp" --target-org $ORG 2>/dev/null
+
+# Setup entities / standard objects need no metadata retrieve:
+#   OpptStageDescription is a Tooling setup entity (query with --use-tooling-api)
+#   AiGenActionItem is a standard object
+
+echo "Retrieval complete. Check force-app/main/default/ for metadata."
+```
+
+---
+
+## Metadata Inspection Queries
+
+### Check All Pipeline Management Components
+
+```bash
+# Settings
+sf data query -q "SELECT enableDealAgent, enableDealAgentAutoApproveAllTasks FROM SalesDealAgentSettings" --target-org $ORG --json 2>/dev/null
+
+# Agent (BotDefinition has no Status column; query Id/DeveloperName only)
+sf data query -q "SELECT Id, DeveloperName FROM BotDefinition WHERE DeveloperName = 'SalesAgent'" --target-org $ORG --json 2>/dev/null
+
+# Agent User
+sf data query -q "SELECT Id, Username FROM User WHERE Username LIKE '%salesmanagementagentuser%'" --target-org $ORG --json 2>/dev/null
+
+# Flows (FlowDefinition is unsupported on the data API — query FlowDefinitionView; use IsActive, not Status)
+sf data query -q "SELECT ApiName, IsActive, IsTemplate FROM FlowDefinitionView WHERE ApiName LIKE '%sales_pipe_mgmt%'" --target-org $ORG --json 2>/dev/null
+
+# Prompt Templates (GenAiPromptTemplate is NOT SOQL-queryable — use the REST endpoint)
+sf api request rest "/services/data/v64.0/einstein/prompt-templates" --target-org $ORG 2>/dev/null | jq -r '.promptRecords[]?.fields.DeveloperName.value'
+
+# Stage Descriptions (Tooling setup entity — requires --use-tooling-api)
+sf data query -q "SELECT COUNT() FROM OpptStageDescription" --target-org $ORG --use-tooling-api --json 2>/dev/null
+
+# Recent Suggestions
+sf data query -q "SELECT COUNT() FROM AiGenActionItem WHERE Type = 'FIELD_UPDATE' AND CreatedDate = TODAY" --target-org $ORG --json 2>/dev/null
+```
+
+---
+
+## Notes
+
+- Not all components are retrievable via Metadata API (e.g., agent user must be queried via SOQL)
+- Component availability varies by org edition and license
+- Template flows (`isTemplate=true`) should not be activated directly — always clone first
+- SOAP API required for `SalesDealAgentSettings` only (CLI returns 'Settings type is unknown'). `EinsteinGptSettings` and `EinsteinCopilotSettings` work with both CLI and SOAP.
+- `BotDefinition` and `BotVersion` use **standard SOQL** — NOT `--use-tooling-api` (Tooling API returns "sObject type not supported"). `BotDefinition` has no `Label` or `Status` column; `BotVersion` exposes `Status`. `GenAiPromptTemplate` is not queryable via SOQL (Tooling or standard) — inspect it via the Metadata API / retrieve.
+- All `sf ... --json` commands piped to jq should include `2>/dev/null` for clean parsing

package/skills/sales-agentforce-pipeline-management-configure/references/opportunity-stages.md

@@ -0,0 +1,246 @@
+# Opportunity Stage Descriptions
+
+The Pipeline Management agent reads stage semantics from the `OpptStageDescription` setup entity (Tooling API), NOT from the standard `OpportunityStage.Description` field.
+
+---
+
+## Storage Entity: `OpptStageDescription`
+
+| Fact | Detail |
+|------|--------|
+| **Entity** | `OpptStageDescription` (setup BPO) |
+| **Fields** | `DeveloperName` (required), `MasterLabel` (required), `OpportunityStageApiName` (required), `Description` (required) |
+| **Access** | Tooling API only — full CRUD |
+| **Scope** | Per-record-type |
+| **Requirement** | Pipeline Management must be enabled |
+
+**CRITICAL — Visibility Prerequisite**: The `OpptStageDescription` Tooling API object is **ONLY visible and accessible AFTER Pipeline Management is enabled** (`SalesDealAgentSettings.enableDealAgent = true`). Before enablement:
+- Tooling API queries return `INVALID_TYPE` or empty results
+- The object does not appear in Tooling API describe calls
+- Setup UI pages for stage descriptions are hidden
+
+**You MUST enable Pipeline Management (Phase 3 in setup-all.sh) BEFORE attempting any OpptStageDescription queries or DML.**
+
+**How it feeds the prompt**: The flow calls `GetOpportunityStageDetailsInvocableAction`, which queries `OpptStageDescription` records and injects them as grounding data into the Recommend Stage for Opportunity prompt template.
+
+---
+
+## Auto-Provisioned Descriptions
+
+**Important**: When Pipeline Management is enabled, the platform MAY auto-provision stage descriptions for all active stages. This behavior was observed in test orgs — MEDDIC-aligned descriptions appeared automatically.
+
+**Always check for existing descriptions BEFORE creating**. If you attempt to create a description for a stage that already has one, you get a `DUPLICATE_VALUE` error.
+
+---
+
+## CLI Automation (Tooling API)
+
+### Query existing stage descriptions
+
+```bash
+sf data query -q "SELECT Id, OpportunityStageApiName, Description FROM OpptStageDescription" \
+  --target-org pipeline-mgmt-org --use-tooling-api --json 2>/dev/null
+```
+
+### Detect stages without descriptions
+
+```bash
+# Get all active stages
+sf data query -q "SELECT MasterLabel, ApiName FROM OpportunityStage WHERE IsActive = true ORDER BY SortOrder" \
+  --target-org pipeline-mgmt-org --json 2>/dev/null
+
+# Get all described stages
+sf data query -q "SELECT OpportunityStageApiName FROM OpptStageDescription" \
+  --target-org pipeline-mgmt-org --use-tooling-api --json 2>/dev/null
+
+# Compare — any active stage NOT in OpptStageDescription needs a description
+```
+
+### Create a stage description
+
+```bash
+sf data create record --sobject OpptStageDescription \
+  --values "DeveloperName='Qualification' MasterLabel='Qualification' OpportunityStageApiName='Qualification' Description='Budget confirmed, decision-maker identified, need validated, timeline discussed. All four BANT criteria must be met to advance past this stage.'" \
+  --target-org pipeline-mgmt-org --use-tooling-api --json 2>/dev/null
+```
+
+### Update an existing stage description
+
+```bash
+sf data update record --sobject OpptStageDescription --record-id <Id> \
+  --values "Description='Updated: Budget confirmed AND authority identified AND need validated AND timeline within 6 months.'" \
+  --target-org pipeline-mgmt-org --use-tooling-api --json 2>/dev/null
+```
+
+### Upsert pattern (create-or-update)
+
+Use this to avoid DUPLICATE_VALUE errors when descriptions may already exist:
+
+```bash
+ORG="pipeline-mgmt-org"
+STAGE_API="Prospecting"
+DESCRIPTION="Initial outreach and qualification. Entry: Lead converted. Exit: Meeting scheduled."
+
+# Check if description exists
+EXISTING_ID=$(sf data query -q "SELECT Id FROM OpptStageDescription WHERE OpportunityStageApiName='${STAGE_API}'" \
+  --target-org $ORG --use-tooling-api --json 2>/dev/null | jq -r '.result.records[0].Id // empty')
+
+if [[ -n "$EXISTING_ID" ]]; then
+  # Update
+  sf data update record --sobject OpptStageDescription --record-id "$EXISTING_ID" \
+    --values "Description='${DESCRIPTION}'" \
+    --target-org $ORG --use-tooling-api --json 2>/dev/null
+else
+  # Create
+  sf data create record --sobject OpptStageDescription \
+    --values "DeveloperName='${STAGE_API}' MasterLabel='${STAGE_API}' OpportunityStageApiName='${STAGE_API}' Description='${DESCRIPTION}'" \
+    --target-org $ORG --use-tooling-api --json 2>/dev/null
+fi
+```
+
+---
+
+## OOTB Default Descriptions
+
+Use the "propose and correct" pattern — present these defaults to the user, ask what doesn't match their process, then deploy the corrected set.
+
+### Standard B2B Stages
+
+| Stage API Name | Description |
+|----------------|-------------|
+| `Prospecting` | Initial outreach and qualification. Entry: Lead converted or manual creation. Exit: Meeting scheduled or qualified out. |
+| `Qualification` | Budget confirmed, decision-maker identified, need validated, timeline discussed. Entry: Prospecting complete. Exit: All BANT criteria met. |
+| `Needs_Analysis` | Deep discovery underway. Pain points validated, technical requirements gathered. Entry: Qualification passed. Exit: Requirements documented. |
+| `Value_Proposition` | Solution presented addressing specific needs. ROI quantified. Entry: Needs analysis complete. Exit: Prospect agrees solution fits needs. |
+| `Id_Decision_Makers` | All stakeholders identified and engaged. Decision process documented. Entry: Value prop accepted. Exit: All decision-makers on board. |
+| `Perception_Analysis` | Prospect evaluating and comparing solutions. Objections being handled. Entry: Decision-makers identified. Exit: Objections resolved, ready for proposal. |
+| `Proposal_Price_Quote` | Formal proposal submitted. Pricing under review. Entry: Perception analysis complete. Exit: Proposal accepted or counter-proposal submitted. |
+| `Negotiation_Review` | Contract terms under discussion. Legal review in progress. Entry: Proposal accepted. Exit: Terms agreed, ready to close. |
+| `Closed_Won` | Deal closed successfully. Contract signed. Entry: Negotiation complete. Exit: None (terminal stage). |
+| `Closed_Lost` | Deal lost. Entry: Any stage. Exit: None (terminal stage). Lost reason required. |
+
+### MEDDIC Methodology
+
+| Stage API Name | Description |
+|----------------|-------------|
+| `Metrics` | Quantify economic impact. Entry: Initial contact. Exit: Customer agrees on measurable value. |
+| `Economic_Buyer` | Identify who controls budget. Entry: Metrics defined. Exit: Economic buyer engaged. |
+| `Decision_Criteria` | Understand evaluation criteria. Entry: Economic buyer identified. Exit: Criteria documented and aligned. |
+| `Decision_Process` | Map decision-making process. Entry: Criteria defined. Exit: Process timeline documented. |
+| `Identify_Pain` | Validate business pain. Entry: Decision process mapped. Exit: Pain confirmed and quantified. |
+| `Champion` | Identify internal advocate. Entry: Pain validated. Exit: Champion actively selling internally. |
+| `Proposal` | Present formal proposal. Entry: Champion engaged. Exit: Proposal accepted. |
+| `Negotiation` | Finalize terms. Entry: Proposal accepted. Exit: Contract signed. |
+
+### SPICED Methodology
+
+| Stage API Name | Description |
+|----------------|-------------|
+| `Situation` | Understand current state. Entry: First contact. Exit: Current state documented. |
+| `Pain` | Identify pain points. Entry: Situation understood. Exit: Pain points validated. |
+| `Impact` | Quantify impact of pain. Entry: Pain identified. Exit: Impact measured and agreed. |
+| `Critical_Event` | Identify urgency driver. Entry: Impact quantified. Exit: Critical event confirmed. |
+| `Decision` | Understand decision process. Entry: Critical event identified. Exit: Decision process mapped. |
+| `Proposal` | Present solution. Entry: Decision process mapped. Exit: Proposal accepted. |
+| `Negotiation` | Finalize terms. Entry: Proposal accepted. Exit: Contract signed. |
+
+---
+
+## Bulk Create Script
+
+```bash
+ORG="pipeline-mgmt-org"
+
+# Standard B2B stages
+declare -a STAGES=(
+  "Prospecting|Initial outreach and qualification. Entry: Lead converted or manual creation. Exit: Meeting scheduled or qualified out."
+  "Qualification|Budget confirmed, decision-maker identified, need validated, timeline discussed. Entry: Prospecting complete. Exit: All BANT criteria met."
+  "Needs_Analysis|Needs Analysis|Deep discovery underway. Pain points validated, technical requirements gathered. Entry: Qualification passed. Exit: Requirements documented."
+  "Value_Proposition|Value Proposition|Solution presented addressing specific needs. ROI quantified. Entry: Needs analysis complete. Exit: Prospect agrees solution fits needs."
+  "Id_Decision_Makers|Id. Decision Makers|All stakeholders identified and engaged. Decision process documented. Entry: Value prop accepted. Exit: All decision-makers on board."
+  "Perception_Analysis|Perception Analysis|Prospect evaluating and comparing solutions. Objections being handled. Entry: Decision-makers identified. Exit: Objections resolved."
+  "Proposal_Price_Quote|Proposal/Price Quote|Formal proposal submitted. Pricing under review. Entry: Perception analysis complete. Exit: Proposal accepted."
+  "Negotiation_Review|Negotiation/Review|Contract terms under discussion. Legal review in progress. Entry: Proposal accepted. Exit: Terms agreed."
+  "Closed_Won|Closed Won|Deal closed successfully. Contract signed. Entry: Negotiation complete. Exit: None (terminal stage)."
+  "Closed_Lost|Closed Lost|Deal lost. Entry: Any stage. Exit: None (terminal stage). Lost reason required."
+)
+
+for stage_line in "${STAGES[@]}"; do
+  API_NAME=$(echo "$stage_line" | cut -d'|' -f1)
+  LABEL=$(echo "$stage_line" | cut -d'|' -f2)
+  DESC=$(echo "$stage_line" | cut -d'|' -f3)
+  
+  # Handle two-field vs three-field format
+  if [ -z "$DESC" ]; then
+    DESC="$LABEL"
+    LABEL="$API_NAME"
+  fi
+  
+  echo "Creating description for stage: $LABEL"
+  sf data create record --sobject OpptStageDescription \
+    --values "DeveloperName='${API_NAME}' MasterLabel='${LABEL}' OpportunityStageApiName='${LABEL}' Description='${DESC}'" \
+    --target-org $ORG --use-tooling-api --json 2>/dev/null
+done
+```
+
+---
+
+## Propose-and-Correct Pattern
+
+Use this workflow with users:
+
+1. **Query active stages** in their org:
+   ```bash
+   sf data query -q "SELECT MasterLabel, ApiName FROM OpportunityStage WHERE IsActive = true ORDER BY SortOrder" --target-org $ORG --json 2>/dev/null
+   ```
+
+2. **Present matching default descriptions** from the tables above
+
+3. **Ask**: "Review these defaults — tell me which ones don't match your process and I'll adjust before deploying"
+
+4. **Apply corrections** based on user feedback
+
+5. **Bulk-create** via Tooling API using the corrected descriptions
+
+---
+
+## Troubleshooting
+
+### Stage suggestions fail
+
+**Symptom**: Next Step suggestions work, but Stage suggestions never appear
+
+**Cause**: Missing stage descriptions (prompt template calls `GetOpportunityStageDetailsInvocableAction` which returns empty if no descriptions exist)
+
+**Fix**: Create descriptions for all active stages
+
+### DUPLICATE_VALUE error
+
+**Symptom**: `sf data create record` fails with "Duplicate value"
+
+**Cause**: Description already exists for that stage
+
+**Fix**: Query existing descriptions, update instead of create
+
+### Stage description not visible in UI
+
+**Symptom**: Created via Tooling API but doesn't show in Pipeline Management setup UI
+
+**Cause**: UI caching or record type mismatch
+
+**Fix**: 
+- Refresh UI (hard refresh: Cmd+Shift+R)
+- Verify `OpportunityStageApiName` matches exact stage API name (case-sensitive)
+- Check if stage is active: `SELECT IsActive FROM OpportunityStage WHERE ApiName = 'YourStage'`
+
+---
+
+## Notes
+
+- Stage descriptions are **per-record-type** (Setup UI has record type dropdown)
+- If multiple record types use different stages, create separate descriptions for each
+- Use **active voice** ("Entry: X happens", not "Entry: When X happens")
+- Include **entry criteria** (what must be true to enter this stage) and **exit criteria** (what must be true to move to next stage)
+- Descriptions feed the LLM prompt — be specific and actionable
+- `OpptStageDescription` is Tooling API only — NOT accessible via standard SOQL
+- Always use `2>/dev/null` on `sf ... --json` piped to jq