@salesforce/afv-skills 1.31.0 → 1.32.0

package/skills/platform-widget-generate/references/widget-meta-directives.md

@@ -0,0 +1,130 @@
+# Widget Meta Directives Reference
+
+The `meta` object on a UEM block carries runtime directives for iteration (`forEach` / `forItem`) and conditional rendering (`if`). Read this file when a widget needs either.
+
+---
+
+## Iteration with forEach / forItem
+
+`forEach` iterates over an array; the block and ALL its children repeat for each item.
+
+### Rules
+
+- Place `forEach` on the `meta` object of the REPEATING block (e.g. a row or card).
+- The value is an expression referencing an array: `{!$attrs.<arrayAttr>}` (or `{!$<outerForItem>.<arrayField>}` for nested loops).
+- `forItem` is required alongside `forEach`. It names the variable bound to the current item and must start with `$`.
+- Inside the `forEach` block, reach the **current item** through the loop variable (`{!$item.X}`) — not by traversing the array path (`{!$attrs.items.X}`, which does not unfold to the current iteration). Top-level references for values that don't change across iterations (`{!$attrs.<unrelatedField>}`) are still valid.
+- `forEach` blocks can be nested — inner loops use their own `forItem` name.
+
+### Example — top-level list
+
+```json
+{
+  "definition": "namespace/repeatingBlock",
+  "meta": { "forEach": "{!$attrs.items}", "forItem": "$item" },
+  "children": [
+    { "definition": "namespace/childBlock1", "attributes": { "content": "{!$item.id}" } },
+    { "definition": "namespace/childBlock2", "attributes": { "content": "{!$item.total}" } }
+  ]
+}
+```
+
+### Example — container holds repeating child
+
+When a container holds repeating items, `forEach` goes on the child — not on the container.
+
+```json
+{
+  "definition": "namespace/block",
+  "children": [
+    {
+      "definition": "namespace/repeatingBlock",
+      "meta": { "forEach": "{!$attrs.items}", "forItem": "$item" },
+      "children": [
+        { "definition": "namespace/childBlock", "attributes": { "content": "{!$item.name}" } }
+      ]
+    }
+  ]
+}
+```
+
+### Example — nested loops
+
+The inner `forEach` references an array on the outer loop variable and uses a distinct `forItem` name.
+
+```json
+{
+  "definition": "namespace/repeatingBlock",
+  "meta": { "forEach": "{!$attrs.orders}", "forItem": "$order" },
+  "children": [
+    { "definition": "namespace/childBlock", "attributes": { "content": "{!$order.id}" } },
+    {
+      "definition": "namespace/repeatingChildBlock",
+      "meta": { "forEach": "{!$order.lineItems}", "forItem": "$line" },
+      "children": [
+        { "definition": "namespace/childBlock1", "attributes": { "content": "{!$line.name}" } },
+        { "definition": "namespace/childBlock2", "attributes": { "content": "{!$line.count}" } }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## Conditional rendering with if
+
+`if` conditionally renders a block. When the expression is `false`, the block and all its children are excluded from the rendered output.
+
+### Rules
+
+- Place `if` on the `meta` object of the block.
+- Use `if` only when the schema has a `lightning__booleanType` property suited to the condition. Bind directly to that property (or to a loop variable holding such a value). If no suitable boolean exists in the schema, do not use `if` — render the block unconditionally instead.
+- Do not lean on the truthiness of strings (`""` vs `"value"`), numbers (`0` vs `1`), or nullable fields — that may render today but is not guaranteed across surfaces. Comparisons, arithmetic, and string operations are not supported.
+- `if` may coexist with `forEach` on the same `meta`. `if` is evaluated first — if `false`, the loop is skipped entirely.
+
+### Example — top-level boolean
+
+```json
+{
+  "definition": "namespace/block",
+  "meta": { "if": "{!$attrs.isVerified}" },
+  "attributes": { "label": "Verified user" }
+}
+```
+
+### Example — boolean nested inside a schema object
+
+```json
+{
+  "definition": "namespace/block",
+  "meta": { "if": "{!$attrs.features.showBanner}" },
+  "attributes": { "text": "Promo banner" }
+}
+```
+
+### Example — boolean inside a forEach loop
+
+```json
+{
+  "definition": "namespace/repeatingBlock",
+  "meta": { "forEach": "{!$attrs.tasks}", "forItem": "$task" },
+  "children": [
+    { "definition": "namespace/block1", "attributes": { "content": "{!$task.title}" } },
+    {
+      "definition": "namespace/block2",
+      "meta": { "if": "{!$task.completed}" },
+      "attributes": { "label": "Done" }
+    }
+  ]
+}
+```
+
+---
+
+## Gotchas
+
+| Issue | Resolution |
+|---|---|
+| `if` bound to a non-boolean (string or number) does not behave as expected | Use `if` only when the schema has a `lightning__booleanType` property; otherwise render the block unconditionally |
+| Nested loops share the same `forItem` name | Pick distinct names (e.g. `$item` outer, `$line` inner) — there is no validation error on collision |

package/skills/sales-agentforce-pipeline-management-configure/SKILL.md

@@ -0,0 +1,268 @@
+---
+name: sales-agentforce-pipeline-management-configure
+description: "Use to configure, set up, or repair the Sales Management agent and Agentforce Pipeline Management in a Salesforce org. Automates metadata creation for flows, prompt templates, permission sets, and data source configuration. TRIGGER when: user wants to enable Pipeline Management, configure Sales pipeline features, set up the Sales Management agent for opportunity field updates (including autonomous updates), connect enabled data sources like Einstein Conversation Insights or Einstein Activity Capture, customize opportunity stage descriptions, configure post-meeting suggestions, verify or audit configuration status, fix partially configured orgs, or troubleshoot Pipeline Management metadata issues. DO NOT TRIGGER when: user wants to build a custom agent (use agentforce-generate), configure general Agentforce tracing (use platform-tracing-agentforce-configure), work with non-Sales agents, or enable Einstein Conversation Insights or Einstein Activity Capture from scratch (provisioning is out of scope)."
+metadata:
+  version: "1.0"
+  minApiVersion: "64.0"
+  relatedSkills:
+    - "agentforce-generate"
+    - "platform-tracing-agentforce-configure"
+  cliTools:
+    - tool: ["curl"]
+      semver: ">=7.0.0"
+    - tool: ["jq"]
+      semver: ">=1.6.0"
+    - tool: ["sf"]
+      semver: ">=2.139.6"
+---
+
+# Agentforce Pipeline Management Configuration
+
+Configure Agentforce Pipeline Management end-to-end in a Salesforce org. This skill handles both greenfield orgs (zero configuration) and partially configured orgs that need repair or completion.
+
+## Scope
+
+- **In scope**: Enabling Pipeline Management, configuring the Sales Management agent, activating/customizing flows (Process Field Update Suggestions, Get Opportunity Grounding Data, Get AI Recommendations from Call Transcripts), prompt template configuration, permission set assignment, data source setup, opportunity stage descriptions, autonomous field update configuration, and partial-org repair.
+- **Out of scope**: Building custom agents from scratch (use `agentforce-generate`). Einstein Conversation Insights or Einstein Activity Capture initial provisioning (those are separate products). Slack app installation. Custom Apex triggers on Opportunity Team Member.
+
+---
+
+## Prerequisites
+
+### You must verify (scripts cannot check or change these)
+
+1. **Edition**: Enterprise, Performance, Unlimited, or Developer Edition with Agentforce for Sales add-on (or Agentforce 1 Sales Edition). Setup **probes** this up front (Step 0) — it fails fast with a license/edition message on an org that can't run Pipeline Management, before asking anything — but edition/license provisioning itself is still admin-owned.
+2. **User permissions**: The executing user needs `View Setup` AND (`Modify All Data` OR `Customize Application`), `Manage AI Agents` AND (`Manage Agentforce Employee Agents` OR `Customize Application`), and `Assign Permission Sets`.
+
+### Enabled automatically by `scripts/setup-all.sh`
+
+The following settings are toggled by setup automatically — do not enable them manually before running the script.
+
+- **Einstein Generative AI** (`EinsteinGptSettings.enableEinsteinGptPlatform`) — **required**; must be on before Agentforce Agent.
+- **Agentforce Agent** (`EinsteinCopilotSettings.enableEinsteinGptCopilot`) — **required**; depends on Einstein Generative AI.
+- **Agentforce Studio / Agent Platform** (`AgentPlatformSettings.enableAgentPlatform`) — **required**; depends on Agentforce Agent and gates the Deal Agent. Core rejects `SalesDealAgentSettings.enableDealAgent` when this is off, surfacing as an opaque Deal Agent activation failure.
+- **Enhanced Notes** (`EnhancedNotesSettings.enableEnhancedNotes`) — **required**; Pipeline Management uses ContentNote as a primary data source.
+- **Opportunity Team** (`OpportunitySettings.enableOpportunityTeam`) — **required**; the suggestion flow uses OpportunityTeamMember and will fail deployment without it.
+- **Pipeline Inspection** (`OpportunitySettings.enablePipelineInspection`) — **required**; provides the UI where reps view and accept/dismiss suggestions. Suggestions still generate without it, but users have nowhere to see them.
+- **Enhanced Email** (`EmailAdministrationSettings.enableEnhancedEmailEnabled`) — **optional but recommended**; only needed for email-body indexing when Einstein Activity Capture is in use.
+- **Pipeline Management** (`SalesDealAgentSettings.enableDealAgent`) — **required**; the feature itself.
+
+---
+
+## Clarifying Questions
+
+> **Run the license preflight FIRST — before asking any of these questions.** As
+> your very first action (right after resolving the org alias), run
+> `bash scripts/setup-all.sh <org-alias> --check-license`. It runs only auth + the
+> capability gate, asks nothing, and changes nothing. **If it exits non-zero**,
+> relay the printed license/edition blocker to the user and **STOP** — do not ask
+> any clarifying question and make no changes. Only when it exits 0 (org is
+> capable — greenfield or already provisioned) proceed to the questions below.
+
+Once the preflight passes, determine:
+
+1. **Greenfield or repair?** Is this a new org that has never had Pipeline Management, or one with partial configuration?
+2. **Data sources**: Which data sources should inform the agent?
+   - Notes (enabled by default)
+   - Emails (requires Einstein Activity Capture)
+   - Voice/Video calls (requires Einstein Conversation Insights)
+   - Enhanced Email (for email body indexing — requires `EmailAdministrationSettings.enableEnhancedEmailEnabled`)
+3. **Autonomous updates**: Should the agent update opportunity fields autonomously, or only suggest updates for user review?
+4. **Which fields should the agent manage? (ask this FIRST, up front — setup is field-selection-driven).** `setup-all.sh` builds the flow with **only the fields you select**, from the start — there is no deploy-both-then-strip step. Ask: *"Which Opportunity fields should the agent suggest values for? The OOTB options are Next Step (`NextStep`) and Opportunity Stage (`StageName`); you can also add custom text fields (e.g. a Competitor Analysis field)."*
+   - **At least 1 field is REQUIRED** — setup aborts (exit 1) if zero fields are selected. There is **no** default to `NextStep`.
+   - **Hard cap: 5 fields total**; OOTB fields count toward it. Selecting more aborts before any change.
+   - Pass the set with `--fields "NextStep,StageName,Risk__c"` in non-interactive runs, or type it at the interactive prompt.
+5. **Per-field prompt customization (all fields EXCEPT `StageName`).** For each selected non-`StageName` field, setup collects an optional **goal** ("You must think about…") and **instruction** (extraction guidance):
+   - **`NextStep`** ships with a curated OOTB managed prompt. Setup only overrides it when you supply a goal/instruction (interactive: it asks whether to customize; non-interactive: pass `--field-goal "NextStep:…"` / `--field-instruction "NextStep:…"`). Skip customization to keep the OOTB prompt.
+   - **Custom fields** always get a goal/instruction (your text, or the script's sensible defaults).
+   - **`StageName` is NOT customizable** — it is a managed picklist template with no override support; setup never prompts for it.
+6. **Custom field eligibility**: Only standard or custom **text** fields on Opportunity are supported — plain Text (`type=string`) or Text Area ≤ 255 (`type=textarea`, `htmlFormatted=false`); length ≤ 255; not Long Text Area (length > 255), Rich Text Area (`htmlFormatted=true`), picklist, or formula. The suggestion is capped at the field's own length. Fields selected in question 4 are wired during `setup-all.sh`; **additional** fields added *after* setup use `scripts/add-field-suggestion.sh <org-alias> <FieldApiName>` (one per field; see Phase 4.3). Both paths enforce the 5-total cap — `add-field-suggestion.sh` refuses to wire a 6th field.
+7. **Opportunity stages**: Opportunity stages are picklist values, and different Opportunity record types may expose different stage subsets. Are standard or custom opportunity stages in use? Do their descriptions need to be defined/updated? Note: `OpptStageDescription` is **global-per-stage** — keyed only by `OpportunityStageApiName`, with no per-record-type column — so a description is written **once per active stage** and applies across every record type that exposes that stage. Setup works the same whether or not the org has Opportunity record types.
+
+---
+
+## Admin Communication Guidelines
+
+**CRITICAL**: This skill serves admin users, not developers. Follow these rules:
+
+1. **Run all bash commands in background** (`run_in_background: true`) - this includes the main setup commands AND any log-tailing for progress monitoring
+2. **Monitor progress without showing commands** - You can tail logs to provide progress updates, but run tail commands in background too. Parse the output and show only friendly updates like "✓ Opportunity Team: enabled". Never show the tail command itself or raw log lines.
+3. **Investigate errors silently** - When something fails, do your diagnosis (check data, run queries, fix environment issues) in background without narrating each step. Only surface the conclusion and action: "I need to create a test opportunity first. Let me do that..." NOT "The --json output is corrupted... let me check... ANSI color codes... let me fix..."
+4. **Narrate in plain language**: Say "Setting up the platform..." NOT "Running setup-all.sh Phase 1.5"
+5. **Hide technical details**: No SOAP responses, curl commands, jq parsing, phase numbers, or script paths unless user asks to debug
+6. **Check exit codes**: Always parse success/failure and translate technical errors to admin-friendly messages
+7. **Set time expectations**: "This takes ~3 minutes..." prevents "is it frozen?" questions
+8. **Handle errors gracefully**: Auto-retry transient failures; explain and offer choices for real blockers
+
+See `references/admin-communication.md` for detailed error translation patterns, examples, and recovery strategies.
+
+## Workflow
+
+**IMPORTANT — Primary Entry Point**: For end-to-end setup, drive `scripts/setup-all.sh`. It handles all prerequisites, enablement, flow deployment, permissions, and verification in the correct dependency order. Only use individual scripts when diagnosing or repairing specific components after `setup-all.sh` has run.
+
+`setup-all.sh` is a **3-phase, field-selection-driven** setup: (1) platform enablement + agent user + PSG assignment; (2) field selection → prompt template creation/activation → stage descriptions (only if `StageName` selected) → prompt verification; (3) flow build (selected fields only), flow activation, agent activation, PSG recalc. It is **safe by default**: suggestions-only mode, no stage-description creation unless asked, and the flow does not go live until the prompts are in place.
+
+#### Canonical agent path — two calls with an interactive tune-loop between them
+
+See `references/canonical-agent-path.md` for the full two-call pattern with code examples, agent rules, narration templates, and internal step map.
+
+**Summary**: Split setup into Call 1 (`--through-phase prompts`) and Call 2 (`--from-phase flow`) with a tune-loop between them where you drive prompt approval per field. Call 2 is MANDATORY — without it no flow exists and no suggestions generate.
+
+#### Unattended / CI path (single call, no tune-loop)
+
+For fully unattended runs (cron/CI, or when the user explicitly declines prompt review):
+
+```bash
+bash setup-all.sh <org-alias> --fields "NextStep,StageName,Risk__c" \
+  [--field-goal "NextStep:<text>"] [--field-instruction "NextStep:<text>"] \
+  [--autonomous] [--create-stage-descriptions] [--skip-prompt-verification] \
+  --non-interactive [--users "a@x.com,b@x.com"]
+```
+
+In single-pass mode the verification step still prints each field's suggestion (informational). Relay them to the user.
+
+#### Flags
+
+See `references/flags.md` for complete flag documentation. Key flags:
+
+- `--check-license` — preflight only (exit 0 = capable, 1 = blocker). Run FIRST.
+- `--through-phase prompts` / `--from-phase flow` — split-run endpoints (mutually exclusive)
+- `--fields "NextStep,StageName"` — required field set (at least 1, max 5)
+- `--autonomous` — enable auto-apply mode (off by default)
+- `--non-interactive` / `--yes` — unattended mode (requires `--fields`)
+- `--users "a@x.com,b@x.com"` — explicit user list for PSG assignment (email-validated)
+
+The phases below explain the decision logic for manual/repair scenarios. See `references/setup-order.md` for step-by-step details.
+
+### Automation Summary
+
+Every configuration step and whether it's CLI-automatable (and how) or UI-only lives in `references/automation-matrix.md`. In short: prerequisites, enablement, flow clone/activation, agent publish/activation, permissions, field suggestions, and stage descriptions are all CLI-automatable (`setup-all.sh` does them in dependency order); only Agent Analytics is UI-only.
+
+---
+
+### Phase 0 — Authentication and Org Assessment
+
+1. **Authenticate** — See `references/auth-and-cli.md`. Always use `2>/dev/null` on `sf --json | jq`.
+
+2. **Assess org state** — Branching signals (NOT PSG existence — PSGs ship with the license even in unconfigured orgs):
+   - **Enablement**: `SalesDealAgentSettings.enableDealAgent` via SOAP readMetadata
+   - **Setup-has-run** (any of): (a) agent user holds `SalesManagementAgentUserPsg`, (b) flow `Process_Field_Update_Suggestions` exists (by ApiName, not label), (c) `BotDefinition` with `AgentTemplate IN ('SalesMgmt__NGASalesAgent','SalesMgmt__SalesAgent')`
+
+3. **Run `scripts/setup-all.sh <org-alias>`** — handles branching automatically:
+   - No enablement + no signals → greenfield (Phase 1)
+   - Partial signals → repair (Phase 3)
+   - All present → verification only
+
+### Phase 1 — Enable Prerequisites and Pipeline Management
+
+**See `references/setup-order.md` for complete scripts.** Enable in dependency order: Einstein GenAI → Agentforce Agent → Agent Platform → Enhanced Notes → Opportunity Team → Pipeline Management → Pipeline Inspection. Then deploy the flow (`scripts/create-flow.sh`) and verify agent architecture (`references/agent-creation.md`).
+
+**What auto-creates on enablement**: agent user + PSGs (auto-assigned). **What you must create**: `BotDefinition:SalesAgent` (via authoring-bundle publish) and the schedule-triggered flow (via template deploy).
+
+### Phase 2 — Assign Permissions
+
+1. **Define Agent Access**: `bash scripts/define-agent-access.sh <org-alias>` — creates custom permset, links into both PSGs. See `references/agent-creation.md` → "Agent Access".
+
+2. **Assign PSG to target users**: **HARD RULE — never bulk-assign.** Grant `SalesManagementUserPsg` only to: (1) the running user, and (2) explicit `--users` list. No enumerate-and-grant.
+
+### Phase 3 — Repair Mode (Partially Configured Org)
+
+See `references/repair-diagnostics.md` for the full checklist. Common issues: flow deactivated → Tooling API `PATCH`; agent not active → `sf agent activate`; prompt template inactive → version round-trip redeploy; agent missing → SOAP toggle off/on.
+
+### Phase 4 — Customize (Admin Decisions Required)
+
+1. **Define Opportunity Stage Descriptions** — Use the "propose and correct" pattern from `references/opportunity-stages.md`. Query active stages, present defaults from reference file, apply user corrections, bulk-create via Tooling API.
+   
+   **IMPORTANT**: Stage descriptions MAY be auto-provisioned when Pipeline Management is enabled (test orgs showed MEDDIC descriptions pre-populated). **Always CHECK for existing descriptions BEFORE attempting to create them**. If descriptions already exist, UPDATE rather than CREATE to avoid duplicates.
+
+2. **Configure additional data sources** — See `references/data-sources.md` for decision table (Einstein Conversation Insights, Einstein Activity Capture, Inbox).
+
+3. **Add custom opportunity field suggestions (AFTER setup)** — Fields chosen at setup time are wired by `setup-all.sh --fields`. To add a **new** field to an already-configured org, run `scripts/add-field-suggestion.sh <org-alias> <FieldApiName>` (e.g. a `Risk__c` field). The script validates the field, fills the canonical template (`assets/field-completion-template.genAiPromptTemplate-meta.xml`), deploys and activates it via the version round-trip, and idempotently wires the field into the live `Process_Field_Update_Suggestions` flow (respecting the 5-field cap). Optional flags: `--label`, `--goal`, `--instruction` (the two field-specific prompt lines), `--verify-with-note` (seed a Note + run a synchronous generation), `--opp <Id>`, `--skip-flow`, `--force`. See `references/field-completion-prompts.md` for mechanics and `references/field-completion-prompt-template.md` for writing the goal/instruction lines.
+
+   > **Naming note**: the prompt-template `<type>` is `einstein_gpt__fieldCompletion` (used in all metadata — never change it). The **Setup UI** (Prompt Builder) labels this category **"Field Generation"** — same thing. Admins should look for "Field Generation", not "Field Completion".
+
+4. **Configure autonomous updates** — Autonomous mode is a single **org-wide** toggle (`SalesDealAgentSettings.enableDealAgentAutoApproveAllTasks`), not a per-field setting: when ON, the agent auto-applies all field suggestions without review; when OFF (the default), every suggestion waits for human approval. It is opt-in via `setup-all.sh --autonomous`. See `references/autonomous-updates.md` for the toggle and safety considerations.
+
+5. **Enable Agent Analytics** — Setup → Einstein Feedback and Monitoring → Agent Analytics (UI-only).
+
+---
+
+## Understanding the Flows
+
+See `references/flow-clone-from-template.md` for complete flow architecture, clone approach, and technical constraints.
+
+**Key facts**: Pipeline Management uses a schedule-triggered flow (`Process_Field_Update_Suggestions`) cloned from the managed template. Detection is by ApiName (not label). The flow calls `getOrExecFieldUpdtSuggestion` with the selected fields — adding a field requires both activating its template AND wiring it into the flow's collection (handled atomically by `add-field-suggestion.sh`). **No suggestions generate until this flow is active.**
+
+---
+
+## Key Considerations
+
+- **Pipeline Management REQUIRES a standalone `BotDefinition:SalesAgent`** — a missing BotDefinition blocks setup. Auto-provisioning creates it in most editions, but where it doesn't, `publish_and_activate_agent()` (in `shared/agent-bundle-publish.sh`, called by `setup-all.sh` and `create-agent.sh`) publishes the bundle from `assets/sales_management_agent.agent` and activates it. Do NOT rely on the `EmployeeCopilotPlanner` fallback — users need the interactive chat surface.
+- Flow runs only when agent is **active** with **Read/Write** on opportunities; agent joins as opportunity team member (watch for Apex triggers on OpportunityTeamMember)
+- Daily limit: 8,000 LLM requests / ~4,000 opportunities. Suggestions expire after 30 days
+- Stage template reads `OpptStageDescription` via `GetOpportunityStageDetailsInvocableAction` — **stage suggestions fail** if any active stage lacks a description
+- **Do NOT use CLI Metadata deploy** for DealAgent enablement — SOAP API v64.0 only (CLI has silent failure mode)
+- **Do NOT enable `BotSettings`/`enableBots`** — legacy messaging bots, unrelated, fails with "Legal Terms" error
+- Pipeline Management does NOT use a managed package — components provisioned directly on enablement
+- Toggle not visible in Setup → verify Sales Cloud EE+ license and Agentforce SKU
+- Always use `2>/dev/null` on `sf ... --json` piped to jq (strips CLI warnings that corrupt JSON)
+
+---
+
+## References
+
+- `references/setup-order.md` — Complete copy-paste setup sequence with all scripts
+- `references/soap-api-enablement.md` — SOAP API patterns for all prerequisites
+- `references/flow-clone-from-template.md` — Flow clone approach with ApiName-based detection
+- `references/agent-creation.md` — Agent creation (auto-provisioning + authoring-bundle publish; the SOAP toggle only re-provisions the agent user and PSGs, not the BotDefinition)
+- `references/field-completion-prompts.md` — Adding custom field suggestions end-to-end (verified v67 pattern, the three requirements, `add-field-suggestion.sh` mechanics, verification)
+- `references/field-completion-prompt-template.md` — Writing the field-specific goal/instruction lines the script consumes
+- `references/opportunity-stages.md` — Stage descriptions + methodologies
+- `references/repair-diagnostics.md` — Partially configured org handling
+- `references/auth-and-cli.md` — Auth methods, CLI compatibility
+- `references/data-sources.md` — Decision table for EAC/ECI/Notes/Enhanced Email
+- `references/autonomous-updates.md` — Auto-apply mode toggle and safety considerations
+- `references/metadata-inventory.md` — Complete inventory of provisioned metadata components
+- `references/automation-matrix.md` — Which setup steps are CLI-automatable (and how) vs UI-only
+- `references/admin-communication.md` — Admin-friendly narration patterns: error-translation table, silent-investigation examples, and per-step narration templates for driving setup conversationally
+
+## Examples
+
+- `examples/custom-prompt-instructions.md` — Custom prompt instruction patterns for methodology alignment and update aggressiveness control
+
+## Standalone Scripts
+
+Executable scripts for each setup phase (run from `scripts/` directory with `sfdx-project.json` in CWD):
+
+- `scripts/setup-all.sh` — **Master orchestration**: 3-phase, field-selection-driven end-to-end setup (auth + enablement + agent user/PSG → field selection + prompt templates + stage descriptions + prompt-verification gate → flow build/activate + agent activate + PSG recalc). Requires `--fields` (aborts if none); interactive by default; safe defaults (suggestions-only, no stage-description creation) with `--field-goal`/`--field-instruction`, `--autonomous`, `--create-stage-descriptions`, `--skip-prompt-verification` opt-in flags and `--non-interactive`/`--yes` for unattended runs
+- `scripts/shared/flow-builder.sh` — flow field-collection helpers sourced by `setup-all.sh`: `build_field_collection` (greenfield — writes a flow wiring only the selected fields), plus `strip_flow_field` / `add_flow_field` / `flow_wired_fields` (repair — reconcile an already-deployed flow's fields in place)
+- `scripts/shared/stage-descriptions.sh` — Phase 4c.5 stage-description creation sourced by `setup-all.sh`; exports `run_stage_descriptions()` (self-gates on `STAGENAME_SELECTED`; sets `STAGE_DESCRIPTIONS_BLOCKED` for the Phase 8.5 summary)
+- `scripts/shared/test-opp.sh` — shared test-opportunity + grounding-note resolution sourced by both verify scripts (`flow-debug-and-verify.sh`, `verify-prompt-generation.sh`); exports `resolve_test_opportunity` (reuse/create/fallback the `[PM-TEST]` test opp, roll CloseDate, seed/refresh the grounding note) and `seed_grounding_note`
+- `scripts/retrieve-settings.sh` — Audit current org settings state
+- `scripts/enable-prerequisites.sh` — Enable prerequisite **settings only** (Einstein GenAI, Agentforce, Enhanced Notes, Opportunity Team) via SOAP — no fields/flow/agent. `setup-all.sh` runs this same enablement inline; use the standalone script only for surgical, non-destructive prerequisite toggling
+- `scripts/enable-deal-agent.sh` — Enable Pipeline Management via SOAP API (standalone helper; `setup-all.sh` enables PM inline — use this only for isolated manual toggling)
+- `scripts/create-flow.sh` — Detect, deploy from template, or activate suggestion flow (falls back to UI guidance)
+- `scripts/create-agent.sh` — Verify/create/activate agent (auto-provisioning + authoring-bundle publish; SOAP toggle only re-provisions agent user/PSGs, not the BotDefinition); also defines Agent Access on completion
+- `scripts/define-agent-access.sh` — Define Agent Access so both users holding `SalesManagementUserPsg` and the autonomous agent user holding `SalesManagementAgentUserPsg` can launch/run the agent (custom permset + `SetupEntityAccess` + `PermissionSetGroupComponent` into both PSGs + recalc)
+- `scripts/deploy-settings.sh` — Deploy non-SOAP settings (Notes, Email, Opportunity)
+- `scripts/add-field-suggestion.sh` — Add an AI field-completion suggestion for any eligible Opportunity text field (validate → fill canonical template → deploy + activate via version round-trip → wire flow; `--verify-with-note` for synchronous generation)
+- `scripts/verify-all.sh` — Comprehensive configuration status check (read-only)
+
+## Admin Verification Tools
+
+The following scripts help admins verify that Pipeline Management is working correctly after setup. Use these to confirm field suggestions are generating as expected.
+
+**Before running either verify script, compose a realistic grounding note and pass it via the `PM_GROUNDING_NOTE` env var.** The AI only generates a suggestion when the opportunity's Note carries real sales context — a generic placeholder grounds on nothing and returns empty, making a working setup look broken. Write a few sentences of a plausible sales call/meeting reflecting the configured `--fields` and any `--field-goal`/`--field-instruction` (e.g. concrete next steps and deadlines for `NextStep`; buyer, budget, pain, and timeline signals for `StageName`). Do not use a rigid template — tailor it to what was configured. Example: `PM_GROUNDING_NOTE="Discovery call with the VP of Sales: confirmed a $250K budget and a Q3 go-live; agreed next steps are a technical deep-dive with IT and an ROI analysis." bash scripts/flow-debug-and-verify.sh <org>`. Absent the env var, the scripts fall back to a generic note.
+
+**Both scripts are invoked separately by the skill but converge on the SAME test opportunity and the SAME grounding note.** They both find-or-create a user-owned opp named `[PM-TEST] Test Pipeline Verification Opp` (the `[PM-TEST]` prefix makes every opp this tooling creates findable via `Opportunity WHERE Name LIKE '[PM-TEST]%'`). On reuse they roll the opp's CloseDate +30 days so it stays flow-eligible, and refresh the grounding note only when the `PM_GROUNDING_NOTE` you pass differs from the stored one (otherwise the existing note is left untouched). Pass the same `PM_GROUNDING_NOTE` value to both invocations so the note is consistent regardless of run order.
+
+- `scripts/flow-debug-and-verify.sh` — Guided two-phase verification of the scheduled suggestion flow.
+  - **flow-debug-start** (`bash scripts/flow-debug-and-verify.sh <org> [opp-id]`) reuses a stable user-owned test opportunity named `[PM-TEST] Test Pipeline Verification Opp` if one is still eligible (so repeated runs don't pile up duplicate opps), otherwise creates it, falls back to any user-owned open opp if creation fails, seeds/refreshes a grounding Note on whichever opp resolves, and prints the flow's **Debug** URL, the opportunity to select, and the exact `verify` command to run afterward — including a trailing baseline count (the pre-run suggestion count). It uses a user-owned opp so the resulting suggestion is visible in the admin's owner-scoped Pipeline Inspection. If no opportunity is available it prints an actionable message and exits 0 without verifying. Relay the URL + opportunity to the user and wait for them to run Debug in Flow Builder against that opportunity — this is the only on-demand path that binds a real `$Record` on a scheduled record-triggered flow (leave rollback mode UNCHECKED so the DML persists).
+  - **verify** (`bash scripts/flow-debug-and-verify.sh <org> <opp-id> verify [baseline]`) runs after the user confirms the debug run finished: it confirms the flow reached its action (agent user added to the Opportunity Team) and polls (~4 min) for the generated `AiGenActionItem` suggestions. **Pass the baseline that flow-debug-start printed** — it is captured *before* the debug run, so the delta is exact; omitting it falls back to weaker absolute detection. The wait between phases happens in the conversation, not inside the script.
+- `scripts/verify-prompt-generation.sh` — Test the prompt template behind a field by calling the Einstein `/generations` API directly. Pass the **field** API name (`bash scripts/verify-prompt-generation.sh <org> <field> [opp-id]` — e.g. `NextStep`, `Risk__c`); it resolves the field to its managed/derived template (a bare, un-namespaced managed name returns `ENTITY_IS_DELETED`) and uses the same user-owned opp selection strategy as `flow-debug-and-verify.sh` (both share one sourced lib: reuse the shared `[PM-TEST] Test Pipeline Verification Opp` → create it → owner-scoped fallback → graceful skip) — the only difference on skip is that no Einstein endpoint call is made. Shows the actual suggestion text generated, helping admins validate custom prompt instructions.
+
+## Agent Assets
+
+- `assets/sales_management_agent.agent` — Agent Script definition for the Sales Management Agent (used when auto-provisioning fails)
+- `assets/sales_management_agent.bundle-meta.xml` — AiAuthoringBundle metadata (deploy with `sf agent publish authoring-bundle --api-name SalesAgent`)
+- `assets/field-completion-template.genAiPromptTemplate-meta.xml` — Canonical `einstein_gpt__fieldCompletion` prompt template with `@@PLACEHOLDERS@@`, filled in by `scripts/add-field-suggestion.sh` (do not deploy directly)

package/skills/sales-agentforce-pipeline-management-configure/assets/field-completion-template.genAiPromptTemplate-meta.xml

@@ -0,0 +1,141 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Canonical field-completion (type einstein_gpt__fieldCompletion) prompt template.
+
+  This is a TEMPLATE with @@PLACEHOLDERS@@ substituted by
+  scripts/add-field-suggestion.sh. Do not deploy this file directly.
+
+  Placeholders:
+    @@DEVNAME@@           - GenAiPromptTemplate developerName, e.g. RecommendRiskforOpp
+    @@MASTERLABEL@@       - human label, e.g. "Recommend Risk for Opportunity"
+    @@FIELD@@             - Opportunity field API name, e.g. Risk__c
+    @@FIELDLABEL@@        - field label, e.g. "Risk"
+    @@CHARCAP@@           - SuggestedNewValue max chars = the field's own length (<=255)
+    @@FIELD_GOAL@@        - one sentence: what to think about for this field
+    @@FIELD_INSTRUCTION@@ - one line: field-specific extraction guidance
+
+  Everything else is the OOTB Pipeline Management instruction body, VERBATIM.
+  Only the field name and the two field-specific lines above ever change.
+
+  Structure invariants (verified against a live org, do NOT alter):
+    - <type>einstein_gpt__fieldCompletion</type>
+    - input <apiName>RelatedEntity</apiName> is platform-fixed for Metadata-API
+      authored templates; the body resolves against <referenceName>Input:Opportunity</referenceName>
+    - body merge fields use {!$Input:Opportunity.<field>}
+    - <relatedField> is object-qualified: Opportunity.<field>
+    - a <templateDataProviders> block is REQUIRED because the body references
+      {!$Flow:sales_pipe_mgmt__GetOppGroundingData.Prompt}
+    - <status>Published</status>
+    - NO <versionIdentifier>/<activeVersionIdentifier> here; the deploy round-trip
+      in add-field-suggestion.sh adds them (deploy -> retrieve identifier -> set
+      active -> redeploy). Never hand-author or guess the identifier.
+-->
+<GenAiPromptTemplate xmlns="http://soap.sforce.com/2006/04/metadata">
+    <description>Field generation prompt for the Opportunity @@FIELDLABEL@@ field</description>
+    <developerName>@@DEVNAME@@</developerName>
+    <masterLabel>@@MASTERLABEL@@</masterLabel>
+    <overridable>false</overridable>
+    <relatedEntity>Opportunity</relatedEntity>
+    <relatedField>Opportunity.@@FIELD@@</relatedField>
+    <templateVersions>
+        <content>You are an AI Assistant to a Sales Representative.
+ You must think about @@FIELD_GOAL@@
+ You must analyze all of the following data sources: call transcript, email, and content note and extract information in order to provide the suggested new value for the &quot;@@FIELDLABEL@@&quot; field of the opportunity, reasoning for the suggested new value, and snippets that capture the most important and relevant information from the data sources. @@FIELD_INSTRUCTION@@
+ The data may not be available in all the &lt;DataSources&gt; and you must strictly generate a SuggestedNewValue, Reasoning, DueDate, and Sources value based on whatever &lt;DataSources&gt; is available. You must strictly only generate an empty and zero values for the following keys: SuggestedNewValue, Reasoning, DueDate, and Sources if the call transcript, email, and content note within the &lt;DataSources&gt; are blank, empty, or contain a placeholder. You must convert all this information into a concise assessment.
+ The call transcript contains metadata, but you must strictly ignore all of this metadata, because you must only extract key insights from the actual conversation.
+
+&lt;DataSources&gt;
+ &quot;&quot;&quot;
+ {!$Flow:sales_pipe_mgmt__GetOppGroundingData.Prompt}
+ &quot;&quot;&quot;
+ Opportunity Current @@FIELDLABEL@@ Value:
+ &quot;&quot;&quot;
+ {!$Input:Opportunity.@@FIELD@@}
+ &quot;&quot;&quot;
+ &lt;/DataSources&gt;
+
+When I ask you to generate Suggested New Value of the &apos;@@FIELDLABEL@@&apos; field, Reasoning, and Snippets, you must strictly follow my instructions below:
+ For the Suggested New Value of the &apos;@@FIELDLABEL@@&apos; field, here are your instructions:
+ &quot;&quot;&quot;
+ The &quot;SuggestedNewValue&quot; must be a maximum of @@CHARCAP@@ characters.
+ If dates and names are available, you must strictly include the relevant dates and the people associated with each item.
+ You must strictly not generate any content or information that you do not have any data or basis on.
+ &quot;&quot;&quot;
+
+For the Reasoning, here are your instructions:
+ &quot;&quot;&quot;
+ Give a clear and concise explanation and make sure that the reasoning, suggested new value of the &apos;@@FIELDLABEL@@&apos; field, sources and snippets must directly support each other consistently and logically.
+ You must explicitly mention all the sources and snippets when you generate your reasoning.
+ If dates and names are available, you must strictly Include the relevant dates and the people associated with each item.
+ You must strictly avoid any redundancies in your reasoning.
+ &quot;&quot;&quot;
+
+For the Snippets, here are your instructions:
+ &quot;&quot;&quot;
+ Each data source is clearly labelled and you must strictly review the data source label and the data within it and make sure that it strictly aligns.
+ You must strictly include the author, owner, or writer of the snippet, for example, you must always include the name of the author, owner, or writer at the beginning of the snippet.
+ The snippet must include direct quotes, specific phrases or sentences from the provided data source as supporting evidence. It must be concrete evidence that supports the reasoning.
+ You must consistently use the correct capitalization and spelling in your snippets and avoid any redundancies.
+ &quot;&quot;&quot;
+
+The value for the &quot;source&quot; object must be the exact record ID extracted from the &lt;DataSources&gt;.
+ You must strictly extract the EmailMessageId for emails.
+ You must strictly extract the latestVideoOrVoiceCallRecordId for call transcripts.
+ You must strictly extract the latestContentNoteRecordId for content notes.
+
+You must generate the output in JSON structure with the following keys: FieldName, SuggestedNewValue, OriginalValue,Reasoning, DueDate, and Sources.
+ Output must be valid JSON that can be parsed without modification.
+ Do not include markdown, code fences, comments, or text outside the JSON object.
+ Do not include any text, explanations, code blocks (like ```json), or markdown. The response must be the raw JSON string only.
+ Always return one and only one valid JSON object.
+ The Sources key must contain an array of objects, each with source and snippet keys.
+
+The character limit of the value for the &quot;Reasoning&quot; key is strictly 250 characters.
+ The character limit of the value for the &quot;Snippet&quot; key is 100.
+ The value for the &quot;DueDate&quot; must strictly be 30 days.
+ {
+ &quot;FieldName&quot;: &quot;@@FIELD@@&quot;,
+ &quot;SuggestedNewValue&quot;: &quot;value&quot;,
+ &quot;OriginalValue&quot;: &quot;{!$Input:Opportunity.@@FIELD@@}&quot;,
+ &quot;Reasoning&quot;: &quot;value&quot;,
+ &quot;DueDate&quot;: &quot;30 days&quot;,
+ &quot;Sources&quot;: [
+ {
+ &quot;source&quot;: &quot;value&quot;,
+ &quot;snippet&quot;: &quot;value&quot;
+ },
+ {
+ &quot;source&quot;: &quot;value&quot;,
+ &quot;snippet&quot;: &quot;value&quot;
+ },
+ {
+ &quot;source&quot;: &quot;value&quot;,
+ &quot;snippet&quot;: &quot;value&quot;
+ }]
+ }
+ After filling in the values for the JSON, check the following items:
+ - The value for the key &quot;SuggestedNewValue&quot; MUST be at most @@CHARCAP@@ characters in length (counting spaces, punctuation, and symbols). Count the characters and if this count is greater than @@CHARCAP@@, you MUST revise the value. Prioritize clarity and conciseness.
+ - You must replace any placeholder that exactly matches the pattern &quot;[Provide:{field api label}]&quot; with an empty string. You must not replace any other text that does not follow this exact pattern.</content>
+        <inputs>
+            <apiName>RelatedEntity</apiName>
+            <definition>SOBJECT://Opportunity</definition>
+            <referenceName>Input:Opportunity</referenceName>
+            <required>true</required>
+        </inputs>
+        <isCitationEnabled>false</isCitationEnabled>
+        <primaryModel>sfdc_ai__DefaultGPT4Omni</primaryModel>
+        <status>Published</status>
+        <templateDataProviders>
+            <definition>flow://sales_pipe_mgmt__GetOppGroundingData</definition>
+            <parameters>
+                <definition>SOBJECT://Opportunity</definition>
+                <isRequired>true</isRequired>
+                <parameterName>RelatedEntity</parameterName>
+                <valueExpression>{!$Input:Opportunity}</valueExpression>
+            </parameters>
+            <referenceName>Flow:sales_pipe_mgmt__GetOppGroundingData</referenceName>
+        </templateDataProviders>
+    </templateVersions>
+    <type>einstein_gpt__fieldCompletion</type>
+    <visibility>Global</visibility>
+</GenAiPromptTemplate>