@salesforce/afv-skills 1.31.0 → 1.32.0

package/skills/sales-agentforce-pipeline-management-configure/references/autonomous-updates.md

@@ -0,0 +1,215 @@
+# Autonomous Updates in Pipeline Management
+
+Pipeline Management generates opportunity field update suggestions by default, but requires manual approval. **Autonomous updates** allow the agent to apply approved suggestions automatically without user intervention.
+
+---
+
+## Safety Default: Suggestion-Only Mode
+
+By default, Pipeline Management operates in **suggestion-only mode**:
+- Agent generates `AiGenActionItem` records (`Type = 'FIELD_UPDATE'`) with suggested field updates
+- Suggestions appear in Sales Console under "Pipeline Management" component
+- Users manually review and approve/reject each suggestion
+- No automatic writes to opportunity fields
+
+This is the **safest mode** for initial deployment and testing.
+
+---
+
+## Global Autonomous Toggle
+
+### Setting: `enableDealAgentAutoApproveAllTasks`
+
+Located in `SalesDealAgentSettings` (SOAP API only — CLI deploy silently fails).
+
+**When enabled**:
+- Agent automatically applies **all** field update suggestions without user approval
+- Suggestions are still logged as `AiGenActionItem` records but are immediately applied
+- Users see updates in Opportunity field history
+- No review workflow
+
+**When disabled** (default):
+- Suggestion-only mode (manual approval required)
+
+---
+
+## Enabling Global Autonomous Updates
+
+### Via SOAP API v64.0
+
+```bash
+ORG="pipeline-mgmt-org"
+AUTH_INFO=$(sf org display --target-org $ORG --json 2>/dev/null)
+ACCESS_TOKEN=$(echo "$AUTH_INFO" | jq -r '.result.accessToken')
+INSTANCE_URL=$(echo "$AUTH_INFO" | jq -r '.result.instanceUrl')
+
+curl -s "${INSTANCE_URL}/services/Soap/m/64.0" \
+  -H "Content-Type: text/xml; charset=UTF-8" \
+  -H "SOAPAction: update" \
+  -d "<?xml version='1.0' encoding='utf-8'?>
+<soapenv:Envelope xmlns:soapenv='http://schemas.xmlsoap.org/soap/envelope/' xmlns:met='http://soap.sforce.com/2006/04/metadata'>
+  <soapenv:Header>
+    <met:SessionHeader>
+      <met:sessionId>${ACCESS_TOKEN}</met:sessionId>
+    </met:SessionHeader>
+  </soapenv:Header>
+  <soapenv:Body>
+    <met:updateMetadata>
+      <met:metadata xsi:type='met:SalesDealAgentSettings' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>
+        <met:fullName>SalesDealAgent</met:fullName>
+        <met:enableDealAgent>true</met:enableDealAgent>
+        <met:enableDealAgentAutoApproveAllTasks>true</met:enableDealAgentAutoApproveAllTasks>
+      </met:metadata>
+    </met:updateMetadata>
+  </soapenv:Body>
+</soapenv:Envelope>" | xmllint --format - 2>/dev/null
+```
+
+### Verification
+
+```bash
+sf data query -q "SELECT enableDealAgent, enableDealAgentAutoApproveAllTasks FROM SalesDealAgentSettings" --target-org $ORG --json 2>/dev/null
+```
+
+**Expected output**:
+```json
+{
+  "enableDealAgent": true,
+  "enableDealAgentAutoApproveAllTasks": true
+}
+```
+
+---
+
+## Per-Field Autonomous Updates
+
+**Status**: Not yet available in current Pipeline Management release (as of API v67.0).
+
+**Future capability**: Salesforce plans to support per-field autonomous toggles, allowing fine-grained control:
+- Enable autonomous updates for `Stage` (high confidence field)
+- Require manual approval for `Amount` (high impact field)
+- Enable autonomous updates for `NextStep` (low risk field)
+
+**Current workaround**: Use global toggle only. If per-field control is required, implement custom Apex trigger to block autonomous updates on specific fields based on business logic.
+
+---
+
+## Daily LLM Request Limits
+
+Pipeline Management has **daily LLM request limits** to prevent quota exhaustion:
+
+| Limit | Value |
+|-------|-------|
+| Max LLM requests per day | 8,000 |
+| Approximate opportunities processed | ~4,000 (2 requests per opportunity: grounding + suggestion) |
+
+The 8,000/day figure was observed live: the suggestion flow's debug log emits `{enqueuedStatus=Successful, currentLLMUsage=N, dailyLLMLimit=8000}`. Confirm the current value for your org/edition — `dailyLLMLimit` in that log line is the source of truth.
+
+**What happens when limit is reached**:
+- Agent stops generating new suggestions until next day (UTC reset)
+- Existing suggestions remain visible and actionable
+- No error messages shown to users
+
+**Monitoring usage**:
+```bash
+# Query suggestion records created today
+sf data query -q "SELECT COUNT() FROM AiGenActionItem WHERE Type = 'FIELD_UPDATE' AND CreatedDate = TODAY" --target-org $ORG --json 2>/dev/null
+
+# Each AiGenActionItem represents 1 field-update suggestion
+# Grounding + suggestion together consume ~2 LLM requests per opportunity
+```
+
+**Recommendations**:
+- Start with suggestion-only mode to gauge usage patterns
+- Enable autonomous updates only after confirming daily volume stays under 4,000 opportunities
+- Monitor `AiGenActionItem` record creation rate
+- Consider stage-based filtering (only generate suggestions for opportunities in specific stages)
+
+---
+
+## Risk Matrix: When to Enable Autonomous Updates
+
+| Scenario | Autonomous Mode | Rationale |
+|----------|-----------------|-----------|
+| Initial deployment | ❌ Disabled | Validate suggestion quality first |
+| Sandbox testing | ✅ Enabled | Test end-to-end flow with real data |
+| Production pilot (< 50 users) | ⚠️ Optional | Depends on confidence in suggestion accuracy |
+| Production rollout (> 50 users) | ❌ Disabled initially | Start with manual approval, enable after 2 weeks |
+| High-value opportunities (> $1M) | ❌ Disabled | Manual approval for high-stakes updates |
+| Standard opportunities (< $100K) | ✅ Enabled | Low risk for autonomous updates |
+
+---
+
+## Disabling Autonomous Updates
+
+To revert to suggestion-only mode:
+
+```bash
+curl -s "${INSTANCE_URL}/services/Soap/m/64.0" \
+  -H "Content-Type: text/xml; charset=UTF-8" \
+  -H "SOAPAction: update" \
+  -d "<?xml version='1.0' encoding='utf-8'?>
+<soapenv:Envelope xmlns:soapenv='http://schemas.xmlsoap.org/soap/envelope/' xmlns:met='http://soap.sforce.com/2006/04/metadata'>
+  <soapenv:Header>
+    <met:SessionHeader>
+      <met:sessionId>${ACCESS_TOKEN}</met:sessionId>
+    </met:SessionHeader>
+  </soapenv:Header>
+  <soapenv:Body>
+    <met:updateMetadata>
+      <met:metadata xsi:type='met:SalesDealAgentSettings' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>
+        <met:fullName>SalesDealAgent</met:fullName>
+        <met:enableDealAgent>true</met:enableDealAgent>
+        <met:enableDealAgentAutoApproveAllTasks>false</met:enableDealAgentAutoApproveAllTasks>
+      </met:metadata>
+    </met:updateMetadata>
+  </soapenv:Body>
+</soapenv:Envelope>" | xmllint --format - 2>/dev/null
+```
+
+---
+
+## Troubleshooting
+
+### Autonomous updates enabled but suggestions still require approval
+
+**Symptom**: `enableDealAgentAutoApproveAllTasks = true` but suggestions appear in UI for manual approval
+
+**Causes**:
+1. **Setting not propagated** — Wait up to 5 minutes after SOAP API call
+2. **User permission mismatch** — Autonomous updates may require specific permission set (verify with Salesforce support)
+3. **Opportunity-level override** — Some orgs have custom validation rules or process builders blocking automatic updates
+
+**Diagnosis**:
+```bash
+# Check setting value
+sf data query -q "SELECT enableDealAgentAutoApproveAllTasks FROM SalesDealAgentSettings" --target-org $ORG --json 2>/dev/null
+
+# Check suggestion status (Subject = the field API name, ParentId = the Opportunity Id)
+sf data query -q "SELECT Id, Subject, Status, ParentId FROM AiGenActionItem WHERE Type = 'FIELD_UPDATE' AND CreatedDate = TODAY LIMIT 10" --target-org $ORG --json 2>/dev/null
+```
+
+### Autonomous updates apply wrong values
+
+**Symptom**: Agent autonomously updates fields but values are incorrect
+
+**Causes**:
+1. **Insufficient grounding data** — Agent lacks recent notes, emails, or call transcripts
+2. **Stage descriptions missing or outdated** — See `references/opportunity-stages.md`
+3. **Prompt template misconfiguration** — Custom prompt templates may override default logic
+
+**Fix**:
+1. Disable autonomous updates immediately
+2. Review `AiGenActionItem` records for patterns (which fields have high error rates — group by `Subject`)
+3. Add or update stage descriptions for frequently misidentified stages
+4. Re-enable autonomous updates after validation
+
+---
+
+## Notes
+
+- Always test autonomous updates in sandbox before production enablement
+- Use suggestion-only mode for at least 2 weeks in production to validate accuracy
+- Monitor field history on opportunities to detect autonomous update patterns
+- Consider custom Apex triggers for org-specific autonomous update rules (e.g., block updates on closed opportunities)
+- SOAP API v64.0+ required for `SalesDealAgentSettings` (CLI deploy silently fails)

package/skills/sales-agentforce-pipeline-management-configure/references/canonical-agent-path.md

@@ -0,0 +1,75 @@
+# Canonical Agent Path — Two Calls with Interactive Tune-Loop
+
+Because an agent-driven run is **always non-interactive** (a piped stdin forces `--non-interactive`), the script cannot pause to let the user shape and approve each field's prompt. So split the run and own the interactive tuning yourself, between the two calls:
+
+```bash
+cd skills/sales-agentforce-pipeline-management-configure/scripts
+
+# CALL 1 — enablement through prompt templates, then STOP before the flow.
+# This call still runs ALL prerequisites: Einstein Generative AI, Agentforce Agent, Enhanced
+# Notes, Opportunity Team, Pipeline Inspection, Pipeline Management enablement, agent-user/PSG
+# provisioning, BotDefinition publish/activate, Agent Access — nothing is skipped.
+bash setup-all.sh <org-alias> --fields "NextStep,Risk__c" \
+  --field-goal "NextStep:<text>" --field-instruction "NextStep:<text>" \
+  --through-phase prompts
+
+# TUNE-LOOP (you drive this, per non-StageName field). Generate a note tailored to the
+# field's instruction, seed it, run a synchronous generation, show the result, and LOOP
+# UNTIL THE USER APPROVES:
+bash add-field-suggestion.sh <org-alias> <Field> --skip-flow --force \
+  --goal "<goal>" --instruction "<instruction>" \
+  --verify-with-note --note "<sample note written to exercise THIS field's instruction>"
+#   → shows "Suggested: …" + "Reasoning: …". Relay both to the user.
+#   → user approves → next field. User wants a change → re-run with adjusted --goal/--instruction/--note.
+#   → NO output (blocked): show why, then ask the user immediately — retry / proceed-unverified / skip.
+#     "proceed" wires the field live but flag it as UNVERIFIED.
+
+# ALSO show the DEFAULT suggestion for every SELECTED field the user left UNCUSTOMIZED
+# (StageName always; NextStep when no goal/instruction was given), so they can decide to
+# keep or change the default even though they didn't tune it:
+bash scripts/verify-prompt-generation.sh <org-alias> <Field> <oppId>
+#   → relay "Suggested / Reasoning". Keep → done. Change NextStep → tune it via add-field-suggestion.sh
+#     (above). Change StageName → adjust its stage descriptions (--create-stage-descriptions).
+
+# CALL 2 — build & activate the flow (approved fields only), activate agent, recalc PSG, verify.
+bash setup-all.sh <org-alias> --fields "NextStep,Risk__c" --from-phase flow
+```
+
+## Rules for the Agent Driving This
+
+- **The tune-loop IS Call-1 prompt verification.** Seeding a note and running `add-field-suggestion.sh --verify-with-note` (showing "Suggested / Reasoning") is how each field's prompt is verified. There is no separate "run prompt verification" step to trigger afterward — if you completed the tune-loop, verification happened.
+- **Show a default suggestion for every SELECTED field, even uncustomized ones.** `StageName` and an uncustomized `NextStep` still generate a default suggestion — surface it (via `verify-prompt-generation.sh <org> <field> <oppId>`) so the user can decide whether to keep or change the default they never explicitly tuned. `StageName` can't be tuned via `add-field-suggestion.sh` (managed picklist template, no override), but its suggestion is shaped by its **stage descriptions** — change those (`--create-stage-descriptions` / edit `OpptStageDescription`) to change it. Never pull in fields the user didn't select.
+- **`StageName` needs stage descriptions to generate.** Its grounding is created in **Call 1** (Phase 4c.5, only when `StageName` is selected) *before* the StageName prompt is tested — so a StageName default can be shown during Call 1's tune-loop.
+- **Call 2 (`--from-phase flow`) is MANDATORY.** Call 1 stops *before* the flow is built, so a run that ends after Call 1 has **no** `Process_Field_Update_Suggestions` flow and generates **zero** scheduled suggestions. The setup is incomplete until Call 2 builds and activates the flow. Always run both calls.
+- **Collect goal/instruction up front** (clarifying Q5) for every non-`StageName` field the user wants customized. Do **not** silently keep the OOTB/default prompt without asking — the script cannot ask for you.
+- **Loop until the user approves** each field's suggestion. Do not treat the first generation as final.
+- Pass the SAME `--fields` set to both calls. StageName (if selected) needs no per-field tune *iteration* (managed picklist template), but DO still show its default suggestion for the user to accept or adjust.
+- To re-inspect any field's prompt outside the loop, run `bash scripts/verify-prompt-generation.sh <org> <field>` (pass the **field** name — e.g. `NextStep`, `Risk__c` — not a raw template name; it resolves the managed/derived template for you).
+- Prefer this two-call path over a single unattended run whenever a human is available to review prompts.
+
+## How to Narrate to the User
+
+Run all commands in background. Narrate in plain language. Check exit codes and translate errors to admin-friendly messages. See `references/admin-communication.md` for detailed patterns.
+
+**Step 0 — License check** (30 sec): "Checking if your org is licensed..." → pass "Ready" or warn "[blocker]"
+
+**Call 1 — Setup platform & prompts** (2-4 min): "Setting up the platform and agent..." → pass "Ready. Let me show you sample suggestions..." or warn "[auto-retry or explain]"
+
+**Tune-loop** (1-4 min per field): "Generating sample for [Field]..." → Show suggestion + "Does this look good?" → Iterate if needed or handle timeout/error with choices
+
+**Call 2 — Activate** (1-2 min): "Activating the automation..." → pass "Pipeline Management is live!" or warn "[explain + offer retry/manual]"
+
+## Internal Step Map (Reference Only)
+
+The narration lines above are the user-facing view. The internal step map below is *your* reference for what each call does — surface it only when a step fails and you need to explain what broke.
+
+**Call 1 — Enablement through prompt templates** *(stops before the flow)* — `--through-phase prompts`
+
+- **Step 1 — Enabling prerequisites & the data source**: SOAP API prerequisites, platform prerequisites (Einstein Generative AI, Agentforce Agent, Enhanced Notes, Opportunity Team, Pipeline Inspection), Pipeline Management enablement, and the autonomous-mode setting.
+- **Step 2 — Provisioning the agent**: agent user + PSG assignment, agent architecture verification, and Agent Access.
+- **Step 3 — Setting up & verifying the field prompt**: create stage descriptions first if `StageName` is selected (its grounding), deploy/activate the selected fields' prompt templates, then the interactive tune-loop — seed a note, generate, relay "Suggested / Reasoning" to the user (including the default for uncustomized `StageName`/`NextStep`), and loop until they approve each field.
+
+**Call 2 — Building & activating the flow** *(goes live)* — `--from-phase flow`
+
+- **Step 4 — Building & activating the flow**: build the schedule-triggered flow with the approved fields only, then activate it.
+- **Step 5 — Finishing & verifying**: user permissions and final verification.

package/skills/sales-agentforce-pipeline-management-configure/references/data-sources.md

@@ -0,0 +1,155 @@
+# Data Sources Decision Table
+
+Pipeline Management uses data sources to generate field update suggestions. The quality and relevance of suggestions directly depends on which data sources are enabled and have recent activity.
+
+---
+
+## Data Source Matrix
+
+| Data Source | What It Provides | Required Setting | Automation Level |
+|-------------|------------------|------------------|-----------------|
+| **Notes** (ContentNote) | Meeting notes, deal notes attached to opportunities | `EnhancedNotesSettings.enableEnhancedNotes` | ✅ SOAP API |
+| **Enhanced Email** | Email body text indexing for deeper analysis | `EmailAdministrationSettings.enableEnhancedEmailEnabled` | ✅ SOAP API |
+| **Einstein Activity Capture** (EAC) | Auto-captured emails + calendar events | Separate product provisioning | ❌ UI setup required |
+| **Einstein Conversation Insights** (ECI) | Voice/video call transcripts | Separate product provisioning | ❌ UI setup required |
+
+---
+
+## Decision Flow
+
+```text
+Does the org have Notes (ContentNote) with recent activity?
+├── Yes → Enable Enhanced Notes ✅ (baseline data source)
+└── No → Create sample notes on open opportunities for testing
+
+Does the org use email-to-opportunity logging?
+├── Yes → Enable Enhanced Email ✅ (enables email body indexing)
+│         → Check if Einstein Activity Capture is provisioned
+│           ├── Yes → Verify EAC is capturing emails (Setup → EAC Configuration)
+│           └── No → Email logging via manual BCC or Salesforce Inbox
+└── No → Skip email data source
+
+Does the org use call recording/transcription?
+├── Yes → Check if Einstein Conversation Insights is provisioned
+│         ├── Yes → Verify transcripts exist: SELECT COUNT() FROM VoiceCall
+│         └── No → Cannot enable without ECI license
+└── No → Skip call transcript data source
+```
+
+---
+
+## Minimum Viable Data Sources
+
+For Pipeline Management to produce useful suggestions, at minimum:
+
+1. **Notes** — must be enabled (lowest barrier)
+2. **Recent opportunity activity** — at least some open opportunities must have activity in the last 7 days
+
+Without any data sources with recent content, the flow will run daily but produce no suggestions.
+
+---
+
+## Verifying Data Source Activity
+
+```bash
+ORG="pipeline-mgmt-org"
+
+echo "=== Notes (primary data source) ==="
+sf data query -q "SELECT COUNT() FROM ContentNote WHERE CreatedDate = LAST_N_DAYS:30" --target-org $ORG 2>/dev/null
+
+echo "=== Emails (if Enhanced Email enabled) ==="
+sf data query -q "SELECT COUNT() FROM EmailMessage WHERE CreatedDate = LAST_N_DAYS:30 AND RelatedToId != null" --target-org $ORG 2>/dev/null
+
+echo "=== Recent opportunity activity ==="
+sf data query -q "SELECT COUNT() FROM Opportunity WHERE LastActivityDate = LAST_N_DAYS:7 AND IsClosed = false" --target-org $ORG 2>/dev/null
+
+echo "=== Voice calls (if ECI enabled) ==="
+sf data query -q "SELECT COUNT() FROM VoiceCall WHERE CreatedDate = LAST_N_DAYS:30" --target-org $ORG 2>/dev/null
+```
+
+**Expected**: Total > 0 for at least Notes and recent opportunity activity.
+
+---
+
+## Enabling Data Sources via API
+
+### Notes (SOAP API)
+
+```bash
+# See references/soap-api-enablement.md Section 3
+curl -s "${INSTANCE_URL}/services/Soap/m/62.0" \
+  -H "Content-Type: text/xml; charset=UTF-8" \
+  -H "SOAPAction: update" \
+  -d "<?xml version='1.0' encoding='utf-8'?>
+<soapenv:Envelope xmlns:soapenv='http://schemas.xmlsoap.org/soap/envelope/' xmlns:met='http://soap.sforce.com/2006/04/metadata'>
+  <soapenv:Header><met:SessionHeader><met:sessionId>${ACCESS_TOKEN}</met:sessionId></met:SessionHeader></soapenv:Header>
+  <soapenv:Body><met:updateMetadata>
+    <met:metadata xsi:type='met:EnhancedNotesSettings' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>
+      <met:fullName>EnhancedNotes</met:fullName>
+      <met:enableEnhancedNotes>true</met:enableEnhancedNotes>
+    </met:metadata>
+  </met:updateMetadata></soapenv:Body>
+</soapenv:Envelope>" | xmllint --format - 2>/dev/null | grep -E "(success|message)" | head -5
+```
+
+### Enhanced Email (SOAP API)
+
+```bash
+# See references/soap-api-enablement.md Section 4
+curl -s "${INSTANCE_URL}/services/Soap/m/62.0" \
+  -H "Content-Type: text/xml; charset=UTF-8" \
+  -H "SOAPAction: update" \
+  -d "<?xml version='1.0' encoding='utf-8'?>
+<soapenv:Envelope xmlns:soapenv='http://schemas.xmlsoap.org/soap/envelope/' xmlns:met='http://soap.sforce.com/2006/04/metadata'>
+  <soapenv:Header><met:SessionHeader><met:sessionId>${ACCESS_TOKEN}</met:sessionId></met:SessionHeader></soapenv:Header>
+  <soapenv:Body><met:updateMetadata>
+    <met:metadata xsi:type='met:EmailAdministrationSettings' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>
+      <met:fullName>EmailAdministration</met:fullName>
+      <met:enableEnhancedEmailEnabled>true</met:enableEnhancedEmailEnabled>
+    </met:metadata>
+  </met:updateMetadata></soapenv:Body>
+</soapenv:Envelope>" | xmllint --format - 2>/dev/null | grep -E "(success|message)" | head -5
+```
+
+### Einstein Activity Capture (UI-Only)
+
+EAC requires separate product provisioning and cannot be fully automated:
+
+1. Setup → Einstein Activity Capture → Settings
+2. Enable for target users or profiles
+3. Configure sync settings (which emails/events to capture)
+4. Wait 24-48 hours for initial sync
+
+### Einstein Conversation Insights (UI-Only)
+
+ECI requires a separate license and provisioning:
+
+1. Setup → Einstein Conversation Insights → Settings
+2. Connect recording provider (Zoom, Teams, etc.)
+3. Enable for target users
+4. Wait for transcripts to populate
+
+---
+
+## Data Source Impact on Suggestions
+
+| Data Source | Suggestion Quality Impact |
+|-------------|--------------------------|
+| Notes only | Basic — relies on manually written notes |
+| Notes + Email | Better — captures communication context automatically |
+| Notes + Email + EAC | Good — full email + calendar activity captured |
+| Notes + Email + EAC + ECI | Best — includes call transcript insights |
+
+**Recommendation**: Enable Notes + Enhanced Email as the baseline (both automatable). Add EAC and ECI if the org has those licenses.
+
+---
+
+## Troubleshooting
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| No suggestions generated despite active flow | No recent data in any source | Create notes on open opportunities, wait 24h |
+| Suggestions low quality | Only notes enabled, notes are sparse | Enable Enhanced Email, add more detailed notes |
+| "VoiceCall not supported" error | ECI not provisioned | Skip ECI-related queries if not licensed |
+| Emails not appearing in suggestions | Enhanced Email not enabled | Enable via SOAP API (see above) |
+| EAC enabled but no emails captured | Sync delay or configuration issue | Check EAC settings, wait 24-48h |

package/skills/sales-agentforce-pipeline-management-configure/references/field-completion-prompt-template.md

@@ -0,0 +1,120 @@
+# Field Completion Prompt Template Guide
+
+This guide is about the **two field-specific lines** you supply when adding a new Opportunity field-completion suggestion. The template structure itself is fixed and owned by `assets/field-completion-template.genAiPromptTemplate-meta.xml`; `scripts/add-field-suggestion.sh` fills it in, deploys, activates, and wires the flow. See `references/field-completion-prompts.md` for the full end-to-end mechanics.
+
+You do **not** author the whole prompt or use Prompt Builder. You only decide two things:
+
+- `--goal` — one sentence naming what the model should think about for this field.
+- `--instruction` — one line of field-specific extraction guidance.
+
+Everything else in the prompt (data-source block, JSON output rules, character self-check, source-ID extraction rules) is the OOTB Pipeline Management body, reused verbatim. Getting the two lines right is the whole job.
+
+---
+
+## Where the two lines land
+
+Inside the fixed template body, the script substitutes:
+
+```text
+You must think about @@FIELD_GOAL@@
+...extract information in order to provide the suggested new value for the "@@FIELDLABEL@@" field... @@FIELD_INSTRUCTION@@
+```
+
+So `--goal` completes "You must think about …" and `--instruction` is appended after the standard extraction sentence. Write them to read naturally in those slots.
+
+The template already enforces: `SuggestedNewValue` ≤ the field's own length, `Reasoning` ≤ 250 chars, `Snippet` ≤ 100 chars, `DueDate` = `"30 days"`, and a `Sources` array of `{source, snippet}` objects (never a flat string array). Do **not** restate or contradict those caps in your two lines — the field length cap is set automatically from the field's `length`.
+
+---
+
+## Worked examples
+
+Each example shows only the two values you pass to the script; the field must be a text field (`type=string`, length ≤ 255).
+
+### Risk (a `Risk__c` custom field, mirroring the OOTB NextStep/Stage prompt shape)
+
+```bash
+--goal "what puts this opportunity at risk of slipping, stalling, or being lost, so the rep can proactively address it"
+--instruction "If there is any mention of budget concerns, competition, decision-maker or stakeholder changes, timeline slips, unresolved objections, or loss of engagement, you must strictly include that in your suggested risk, reasoning, and snippets."
+```
+
+### Next Strategic Initiative (`Next_Strategic_Initiative__c`, Text 255)
+
+```bash
+--goal "the customer's strategic business goal or initiative that this opportunity supports"
+--instruction "Focus on business outcomes in the customer's own words (look for \"our goal is\", \"we're trying to\", \"strategic priority\"); if multiple goals appear, pick the one most frequently or most recently emphasized."
+```
+
+### Primary Competitor (`Primary_Competitor__c`, Text 255)
+
+```bash
+--goal "which competitors the prospect is evaluating and how they compare"
+--instruction "Extract explicit competitor names and the specific concern or comparison raised; if several are mentioned, choose the one discussed most or first."
+```
+
+---
+
+## Writing good goal/instruction lines
+
+### ✅ Good
+
+- **Specific about what to extract** — names the signals to look for.
+- **Grounded** — tells the model to use only what's in the data sources.
+- **Customer-centric** — business outcomes, not product features.
+- **Handles absence** — the fixed body already returns empty values when no data exists; your instruction should reinforce, not fight, that.
+
+### ❌ Avoid
+
+| Anti-pattern | Example | Why it fails |
+|---|---|---|
+| Too vague | "Update this field based on the opportunity." | No guidance on what to extract. |
+| Assumes data exists | "Populate with the customer's Q3 revenue goal and sponsor's name." | Forces fabrication when the data is absent. |
+| Product-centric | "List which features the customer wants." | Ignores the customer's business context. |
+| Restating caps wrongly | "SuggestedNewValue must be 500 characters." | The template already caps at the field length; a conflicting number confuses the model. |
+
+---
+
+## Verifying a new field's output
+
+Use `--verify-with-note` (seeds a ContentNote, then calls the synchronous `/generations` endpoint) or call it manually:
+
+```bash
+sf api request rest "/services/data/v64.0/einstein/prompt-templates/<TemplateName>/generations" \
+  --method POST --target-org "$ORG" \
+  --body '{"isPreview":false,"inputParams":{"valueMap":{"Input:Opportunity":{"value":{"id":"<oppId>"}}}},"additionalConfig":{"numGenerations":1,"temperature":0,"applicationName":"PromptTemplateGenerationsInvocable"}}'
+```
+
+A correct response looks like this (note the object-form `Sources` and the literal `"30 days"` DueDate — verified live):
+
+```json
+{
+  "FieldName": "Deal_Momentum__c",
+  "SuggestedNewValue": "Low momentum due to budget freeze, no executive sponsor, and competitor evaluation.",
+  "OriginalValue": "",
+  "Reasoning": "The June 20 call with Sarah Chen flagged a Q3 budget freeze and departure of the sponsor; a note records active evaluation of competitor Onyx.",
+  "DueDate": "30 days",
+  "Sources": [
+    { "source": "069SB000008L2yHYAS", "snippet": "Sarah Chen: budget is frozen until the Q3 review." }
+  ]
+}
+```
+
+The real (async) suggestions land as `AiGenActionItem` records — query by `ParentId` (Opportunity Id) and `Subject` (field API name), `Type = 'FIELD_UPDATE'`. There is no `FieldCompletion` object.
+
+---
+
+## Common issues
+
+| Issue | Cause | Fix |
+|---|---|---|
+| Field always returns empty | Instruction too strict, or opportunity has no recent notes/emails/calls | Broaden the instruction; seed a note (`--verify-with-note`) or use an active opportunity |
+| Model fabricates data | Goal/instruction implies data that isn't there | Reword to "if present"; the fixed body already forbids ungrounded output |
+| Output exceeds field length | Field length ≤ your content need | Pick a field with adequate length; the cap is the field's own `length` |
+| Template never activates | Version round-trip skipped or identifier hand-authored | Let the script own activation — never guess `<activeVersionIdentifier>` |
+
+---
+
+## Further reading
+
+- `references/field-completion-prompts.md` — full deploy/activate/wire/verify mechanics and the three requirements for a field to produce suggestions.
+- `references/data-sources.md` — enabling Einstein Conversation Insights, Activity Capture, and Enhanced Email so `GetOppGroundingData` has content.
+- `references/flow-clone-from-template.md` — how `Process_Field_Update_Suggestions` invokes `getOrExecFieldUpdtSuggestion`.