@salesforce/afv-skills 1.31.0 → 1.32.0

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

@@ -0,0 +1,149 @@
+# Field Completion Prompt Templates
+
+This reference covers adding Pipeline Management field-update suggestions for Opportunity text fields beyond the two the pipeline ships with (`NextStep` and `StageName`).
+
+Everything here was verified end-to-end on a live org (deploy → activate → generate). The canonical XML lives at `assets/field-completion-template.genAiPromptTemplate-meta.xml`; the automation that fills it in and wires the flow is `scripts/add-field-suggestion.sh`.
+
+> **Naming note — "Field Generation" vs "Field Completion".** The prompt-template metadata `<type>` is `einstein_gpt__fieldCompletion` (used everywhere in metadata, filenames, and this repo — do not change it). In the **Setup UI** (Prompt Builder), Salesforce labels this template category **"Field Generation"**. They are the same thing: an admin looking in Setup should look for **Field Generation**, not "Field Completion".
+
+---
+
+## Use the script — do not hand-author
+
+**`scripts/add-field-suggestion.sh` is the supported path.** It performs the full, order-sensitive sequence deterministically so you never have to guess version identifiers or edit the flow by hand:
+
+> **Field cap:** Pipeline Management manages at most **5 Opportunity fields total**, and the two OOTB fields (`NextStep`, `StageName`) count toward that 5. `add-field-suggestion.sh` enforces this — when the flow already wires 5 fields, adding a new one fails with a "field cap reached" error (adding a field already wired is an idempotent no-op and is never blocked). To add a 6th, remove one first (decline an OOTB field during `setup-all.sh`, or strip it from the flow).
+
+
+```bash
+cd scripts
+./add-field-suggestion.sh <org-alias> <FieldApiName> \
+  [--label "Human Label"] \
+  [--instruction "one line of field-specific extraction guidance"] \
+  [--goal "one sentence: what the model should think about"] \
+  [--name RecommendXforOpp] \
+  [--opp <OpportunityId>] \
+  [--verify-with-note] \
+  [--skip-flow]
+```
+
+Example (the exact call verified on the org):
+
+```bash
+./add-field-suggestion.sh pipeline-mgmt-org Deal_Momentum__c \
+  --label "Deal Momentum" \
+  --goal "how much forward momentum this deal has and what is stalling it" \
+  --instruction "Summarize momentum signals: engagement cadence, stakeholder involvement, and blockers." \
+  --verify-with-note
+```
+
+What the script does, in order:
+
+1. **Validate the field** — describes the Opportunity and confirms the field is plain Text (`type=string`) or Text Area ≤ 255 (`type=textarea`, not `htmlFormatted`), `updateable`, not calculated, length ≤ 255. If the field exists in the Tooling `FieldDefinition` but not in the describe, it reports "field has no FLS" and prints the exact `FieldPermissions` grant command instead of failing silently.
+2. **Fill the canonical template** — substitutes placeholders into `assets/field-completion-template.genAiPromptTemplate-meta.xml`, preserving the OOTB instruction body verbatim.
+3. **Deploy + activate (the version round-trip)** — deploys `Published` with no version identifiers, retrieves the platform-generated `<versionIdentifier>`, sets it as `<activeVersionIdentifier>`, and redeploys to activate. Confirms active via the `/einstein/prompt-templates` endpoint.
+4. **Wire the flow** — idempotently adds the field API name to the `Process_Field_Update_Suggestions` flow's `AddOppFieldsToCollection` assignment (skipped with `--skip-flow`).
+5. **Verify (optional, `--verify-with-note`)** — seeds a ContentNote on a sample opportunity and calls the synchronous `/generations` endpoint, printing the generated JSON.
+
+Only read the rest of this doc if you need to understand *why* the pattern is shaped the way it is, or to debug a failure.
+
+---
+
+## Prerequisites
+
+- The field must be a **standard or custom text field** on Opportunity — plain Text (`type=string`) or Text Area ≤ 255 (`type=textarea`, not `htmlFormatted`). Long Text Area (length > 255), Rich Text Area (`htmlFormatted`), picklist, formula, and non-text fields are not supported.
+- `SuggestedNewValue` is capped at the **field's own length** (≤ 255). The script sets the cap from the field's `length` automatically.
+- The field must be **FLS-accessible** to the running user. A freshly deployed custom field has no field-level security and is invisible to `sf sobject describe` until you grant it — this is the single most common first-run failure.
+- A field can have only **one** field-completion prompt template.
+
+---
+
+## Verified template structure (v67)
+
+The canonical asset is the source of truth. The invariants below are what make it work; do not "simplify" them.
+
+| Element | Correct value | Common wrong value to avoid |
+|---------|---------------|-----------------------------|
+| `<type>` | `einstein_gpt__fieldCompletion` | `field_generation` |
+| Input `<apiName>` | `RelatedEntity` (platform-fixed for MDAPI-authored templates) | `Opportunity` |
+| Input `<referenceName>` | `Input:Opportunity` | — |
+| Body merge fields | `{!$Input:Opportunity.<field>}` | `{!$Input:Opportunity}` |
+| `<relatedField>` | object-qualified: `Opportunity.<field>` | bare `<field>` |
+| Grounding | a `<templateDataProviders>` block (`flow://sales_pipe_mgmt__GetOppGroundingData`) is **required** | omitting it |
+| `<status>` | `Published` | `Draft` |
+| Version | none at author time — added by the deploy round-trip | hand-authored `versionNumber` / `activeVersion` |
+
+There is **no** `templateType`, `versionNumber`, or `activeVersion` element. The correct activation field is `<activeVersionIdentifier>`, and its value is the platform-generated `<versionIdentifier>` returned by a retrieve — never hand-authored or guessed.
+
+**`GenAiPromptTemplate` IS CLI-retrievable** for user-created templates (this is how the script gets the version identifier). Only the managed `sales_pipe_mgmt__*` templates are non-retrievable. Any doc or comment claiming user templates cannot be retrieved is wrong and was the root cause of prior version-identifier guessing.
+
+The instruction body is the OOTB Pipeline Management body verbatim; only the field name and two field-specific lines (goal + instruction) change. Character caps inside the body: `SuggestedNewValue` = the field length, `Reasoning` = 250, `Snippet` = 100, `DueDate` = `"30 days"`.
+
+---
+
+## The three requirements for a field to produce suggestions
+
+A field generates `AiGenActionItem` records only when **all three** hold:
+
+1. **Template deployed and activated** — `<status>Published</status>` with a valid `<activeVersionIdentifier>` (the script's round-trip).
+2. **Field added to the flow** — the field API name is a `<stringValue>` in the `AddOppFieldsToCollection` assignment (collection `OpportunityFields`), which feeds the `getOrExecFieldUpdtSuggestion` action's `fieldApiNames` parameter.
+3. **Field FLS-accessible** — the running/agent user can read and edit the field.
+
+Missing any one produces zero suggestions with no error.
+
+---
+
+## Data source grounding flow
+
+Every field-completion template references `{!$Flow:sales_pipe_mgmt__GetOppGroundingData.Prompt}` — a PromptFlow (not a schedule-triggered flow) provisioned by Pipeline Management. It gathers `ContentNote`, `EmailMessage` (if Einstein Activity Capture is on), and call transcripts (if Einstein Conversation Insights is on) from the last 30 days and formats them into the prompt input.
+
+Do **not** change this reference, invoke the flow directly, or build your own replacement. See `references/data-sources.md` for enabling the underlying data products.
+
+---
+
+## Verifying generation
+
+Two ways to confirm a template works:
+
+**Synchronous (deterministic, preferred for testing)** — the `/generations` endpoint returns the model output directly, proving prompt + grounding + field binding are all correct:
+
+```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"}}'
+```
+
+`.generations[0].text` is the JSON output; `.prompt` is the fully resolved prompt. Note `isPreview` **must** be `false` — preview mode cannot resolve the `GetOppGroundingData` data provider (a preview-mode limitation, not a config error). This is exactly what `--verify-with-note` runs.
+
+**Asynchronous (the real pipeline)** — suggestions land as `AiGenActionItem` records ~3 minutes after the schedule-triggered flow runs. Query them by Opportunity and field:
+
+```bash
+sf data query -q "SELECT Id, Subject, Status, SuggestedNewValue FROM AiGenActionItem WHERE Type = 'FIELD_UPDATE' AND ParentId = '<oppId>' ORDER BY CreatedDate DESC" --target-org "$ORG" --json 2>/dev/null
+```
+
+`ParentId` = the Opportunity Id (filterable), `Subject` = the field API name (e.g. `Risk__c`). Poll ≥ 240s before concluding failure — a short poll is the #1 false negative. There is **no** `FieldCompletion` object.
+
+---
+
+## Troubleshooting
+
+### No suggestions generated (async)
+Check the three requirements above in order: is the template active (`/einstein/prompt-templates`)? Is the field in the flow's `AddOppFieldsToCollection` collection? Does the running user have FLS? Then confirm the grounding flows are active (`SELECT ApiName, IsActive FROM FlowDefinitionView WHERE NamespacePrefix='sales_pipe_mgmt'`) and that the test opportunity is eligible (`IsClosed=false`, `CloseDate` within +90 days) with recent notes/emails/calls. Poll ≥ 240s.
+
+### `/generations` returns empty SuggestedNewValue
+The template is fine; the opportunity has no grounding data in the last 30 days. Seed a ContentNote (`--verify-with-note` does this) or use an opportunity with recent activity.
+
+### Field "not found on Opportunity"
+The field has no FLS and is invisible to describe. The script detects this and prints the `FieldPermissions` grant; run that command, then re-run.
+
+### Deploy succeeds but template never activates
+You likely skipped the version round-trip or hand-authored an identifier. Let the script own activation — deploy Published with no identifiers, retrieve the real `<versionIdentifier>`, set `<activeVersionIdentifier>`, redeploy.
+
+---
+
+## Notes
+
+- Only **text fields** (`type=string`, length ≤ 255) are supported.
+- Each field gets exactly **one** template; re-running the script for an existing field is idempotent.
+- Suggestions are `AiGenActionItem` records; `DueDate` of `"30 days"` means they expire after 30 days.
+- Always use `2>/dev/null` on `sf … --json` piped to jq, and `sf api request rest` (not raw curl) on this org.

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

@@ -0,0 +1,13 @@
+# setup-all.sh Flags Reference
+
+- `--check-license` — **preflight only**: run auth + the capability gate, then exit (0 = capable, 1 = unlicensed with a printed blocker). Takes no `--fields`, asks nothing, changes nothing. Run this FIRST, before any clarifying question (Step 0 above).
+- `--through-phase prompts` — run enablement → provisioning → prompt-template deploy/activate, then **stop before the flow is built**. Hands off to the agent tune-loop. (Call 1 above.)
+- `--from-phase flow` — skip the already-done enablement/provisioning/templates and **resume at the flow build** (build + activate flow, agent, PSG recalc, final verify). Pass the same `--fields`. (Call 2 above.) Mutually exclusive with `--through-phase`.
+- `--fields "NextStep,StageName,Risk__c"` — comma-separated Opportunity field API names to manage. **At least 1 is required**; setup aborts if zero are selected (no default to `NextStep`). Max 5 (OOTB fields count). Required in `--non-interactive` mode; interactive mode prompts for it. The flow is built with **only** these fields.
+- `--field-goal "FieldName:<text>"` — custom goal for a specific field (repeatable; format `Field:text`). Only meaningful for non-`StageName` fields.
+- `--field-instruction "FieldName:<text>"` — custom instruction for a specific field (repeatable; same format). For `NextStep`, supplying either flag deploys an OVERRIDE of the OOTB managed prompt; omit both to keep the OOTB prompt.
+- `--skip-prompt-verification` — bypass the Phase 4e prompt-verification step entirely (which seeds a test opportunity + note and shows generated suggestions before activating the flow). In `--non-interactive` runs the step still **runs and prints** the generated suggestions (informational) — only the interactive yes/no *gate* is dropped, so the flow proceeds without blocking. **When you drive setup non-interactively (e.g. as an agent), relay the printed suggestions back to the user** so they get the review the interactive gate would have given.
+- `--autonomous` — enable autonomous field updates (`enableDealAgentAutoApproveAllTasks=true`); the agent auto-applies suggestions with no human review. Omit to keep suggestions-only. In an interactive run the script asks; in `--non-interactive` mode it stays off unless the flag is passed.
+- `--create-stage-descriptions` — create sales-methodology stage descriptions (needed only for `StageName` suggestions, and only prompted/relevant when `StageName` is in `--fields`). Omit to skip. Never auto-created silently in non-interactive mode.
+- `--non-interactive` / `--yes` — run without prompts (also implied when stdin is not a TTY). Requires `--fields`. Combined with the opt-in flags this gives fully unattended setup; without them the run stays on the safe defaults.
+- `--users "a@x.com,b@x.com"` — explicit comma-separated usernames to also grant the `SalesManagementUserPsg`, in addition to the running user. This is the **only** way to add users in a non-interactive run. **NEVER** query all users / all standard users and bulk-assign the PSG — grant only the running user plus the explicit `--users` (or interactively-typed) list. Email format is validated — each value must match a valid email pattern.

package/skills/sales-agentforce-pipeline-management-configure/references/flow-clone-from-template.md

@@ -0,0 +1,447 @@
+# Flow Clone from Template
+
+The schedule-triggered flow for Pipeline Management must be cloned from the template `sales_pipe_mgmt__OppSuggGenSchFlow`. This template is provisioned when Pipeline Management is enabled but never activates itself.
+
+## Why Clone Instead of Build
+
+The template flow contains:
+- Complete flow body with all elements and connectors
+- Invocable action calls using `getOrExecFieldUpdtSuggestion` action type (NOT `generatePromptResponse`)
+- Namespace-prefixed references to prompt templates (`sales_pipe_mgmt__RecommendStageforOpp`, `sales_pipe_mgmt__RecommendNextStepforOpp`)
+- Bot definition lookups and opportunity team member assignment logic
+- Schedule trigger configuration
+
+Building this from scratch would require knowing:
+- Exact action type and input parameters
+- Internal action names
+- Flow element connection paths
+- Variable declarations and assignments
+
+The template already has all of this correct — cloning preserves the entire working structure.
+
+---
+
+## Flow Detection: ApiName is primary; SourceTemplateId is best-effort
+
+`SourceTemplateId` is a real field on `FlowDefinitionView` (confirmed in API v67.0). The
+Setup-UI "Save As" clone path populates it with the template's fully-qualified name
+(e.g., `sales_pipe_mgmt__OppSuggGenSchFlow`). **However, a Metadata-API deploy of the
+pre-retrieved template (the PRIMARY clone path — Method 1) does NOT populate
+`FlowDefinitionView.SourceTemplateId`**, even though the deployed XML carries the
+`<sourceTemplate>` element and the flow is fully active and wired. Org-verified on a
+fresh SDB3 org: the `SourceTemplateId` query returned zero rows while the flow was
+active. So detect by **ApiName first**, and treat `SourceTemplateId` as a best-effort
+signal that only the UI path sets.
+
+**Primary approach** (by ApiName — reliable after both the deploy and the UI paths):
+```bash
+sf data query -q "SELECT Id, ApiName, IsActive FROM FlowDefinitionView WHERE ApiName='Process_Field_Update_Suggestions' AND IsTemplate=false" --target-org pipeline-mgmt-org --json 2>/dev/null
+```
+
+**Supplementary approach** (by `SourceTemplateId` — matches only UI "Save As" clones, empty after a Metadata-API deploy):
+```bash
+sf data query -q "SELECT Id, ApiName, IsActive FROM FlowDefinitionView WHERE SourceTemplateId='sales_pipe_mgmt__OppSuggGenSchFlow' AND IsTemplate=false" --target-org pipeline-mgmt-org --json 2>/dev/null
+```
+
+**Incorrect approach** (label-based):
+```bash
+# DO NOT USE — fragile, language-dependent
+sf data query -q "SELECT Id, ApiName, IsActive FROM FlowDefinitionView WHERE IsTemplate=false AND Label LIKE '%Field Update%'" --target-org pipeline-mgmt-org --json 2>/dev/null
+```
+
+**Why label-based detection fails**:
+- Labels can be changed by admins
+- Labels are translated in multi-language orgs
+- Multiple flows could have similar labels
+- Not the intended API design
+
+---
+
+## Clone Approach
+
+Two methods are available:
+
+1. **Primary — Deploy pre-retrieved template** (fully automated via `scripts/create-flow.sh`)
+2. **Fallback — Setup UI "Save As"** (if deploy fails due to org-specific constraints)
+3. **Verify** the clone exists and has `SourceTemplateId` set
+4. **Activate** if saved as Draft (via retrieve → transform status → deploy)
+
+---
+
+## Method 1: Deploy Pre-Retrieved Template (PRIMARY)
+
+The skill includes a complete flow template retrieved from a live org (`assets/pipeline_management_flow.flow-meta.xml`, 548 lines, API v67.0). This template:
+- Contains all flow elements, connectors, action calls, variables, and schedule trigger
+- Includes `<sourceTemplate>sales_pipe_mgmt__OppSuggGenSchFlow</sourceTemplate>` in the flow body (records provenance in the metadata; note this does **not** populate the queryable `FlowDefinitionView.SourceTemplateId` — detect the clone by ApiName, see "Flow Detection" above)
+- Sets `<status>Active</status>` — deploys ready to run
+- Uses `getOrExecFieldUpdtSuggestion` action type with correct input parameters
+
+**Usage:**
+```bash
+bash scripts/create-flow.sh <org-alias>
+```
+
+**What it does:**
+1. Checks if a clone already exists (by SourceTemplateId or naming convention)
+2. If missing: copies template to `force-app/main/default/flows/`, updates `startDate` to today
+3. Deploys via `sf project deploy start`
+4. If deploy fails: falls back to Setup UI guidance
+
+**Why this works**: While you cannot RETRIEVE the managed template via API, you CAN deploy a flow that references it as `sourceTemplate`. The platform accepts the deployment because the flow body is valid metadata — the namespace protection only blocks reads, not writes of clones.
+
+**When deploy may fail:**
+- Org has flow governance rules blocking new Active schedule-triggered flows
+- API version mismatch (template uses v67.0; org may be on older API)
+- Missing prerequisites (Pipeline Management not enabled, template not provisioned)
+- Permission issues (user lacks `ManageFlows` permission)
+
+---
+
+## Method 2: Setup UI "Save As" (FALLBACK)
+
+If the programmatic deploy fails, the Setup UI method always works:
+
+1. Setup → Flows → Find "Process Field Update Suggestions" (template, marked with template icon)
+2. Open the flow → Click **"Save As"** → New label: "Process Field Update Suggestions" → Save
+3. The platform creates a full copy with all flow elements, connectors, and action calls intact
+4. **Activate** the new flow (it saves as Draft by default)
+5. The platform sets `SourceTemplateId` automatically on the clone
+
+---
+
+## Why Direct Template Retrieval Fails (Reference)
+
+**Critical finding (verified)**: The template flow `sales_pipe_mgmt__OppSuggGenSchFlow` is in a managed namespace. **Neither programmatic retrieval method works**:
+
+- **CLI retrieve**: `sf project retrieve start --metadata "Flow:sales_pipe_mgmt__OppSuggGenSchFlow"` → FAILS with "Entity of type 'Flow' named 'sales_pipe_mgmt__OppSuggGenSchFlow' cannot be found"
+- **SOAP readMetadata**: Returns `<records xsi:nil="true"/>` — the managed package prevents metadata reads even with a valid session
+
+Both methods were tested against a real org (orgfarm-88724451ea, API v64.0). This is by design — managed namespace flows are protected from external metadata reads.
+
+**However**, the pre-retrieved template approach works because:
+1. We retrieved the flow from a live org where it was ALREADY CLONED (user-space clone is readable)
+2. Deploying a flow with `<sourceTemplate>` is a write operation — not subject to managed namespace read protection
+3. The deployed flow registers correctly with `SourceTemplateId` for future detection
+
+### What the template contains
+
+- Flow metadata (`<fullName>`, `<label>`, `<status>`, `<isTemplate>`)
+- All flow elements (`<actionCalls>`, `<assignments>`, `<decisions>`, `<loops>`, etc.)
+- All connectors (`<connector>` with `<targetReference>`)
+- All variable declarations
+- Schedule configuration (`<startDate>`, `<frequency>`)
+- Action call parameters (`getOrExecFieldUpdtSuggestion` with `recordId`, `fieldApiNames`, `agentUserId`, `agentBotDefinitionId`)
+
+---
+
+## Step 2: Transform the XML
+
+```bash
+TEMPLATE_FILE="force-app/main/default/flows/sales_pipe_mgmt__OppSuggGenSchFlow.flow-meta.xml"
+NEW_FILE="force-app/main/default/flows/Process_Field_Update_Suggestions.flow-meta.xml"
+
+# Copy template to new file
+cp "$TEMPLATE_FILE" "$NEW_FILE"
+
+# Transform metadata (macOS sed syntax — use sed -i '' on macOS, sed -i on Linux)
+# 1. Rename the flow
+sed -i '' 's|<fullName>sales_pipe_mgmt__OppSuggGenSchFlow</fullName>|<fullName>Process_Field_Update_Suggestions</fullName>|g' "$NEW_FILE"
+
+# 2. Change the top-level flow label ONLY (first occurrence; non-greedy to avoid corrupting nested element labels)
+sed -i '' '0,/<label>[^<]*<\/label>/s|<label>[^<]*</label>|<label>Process Field Update Suggestions</label>|' "$NEW_FILE"
+
+# 3. Mark as non-template
+sed -i '' 's|<isTemplate>true</isTemplate>|<isTemplate>false</isTemplate>|g' "$NEW_FILE"
+
+# 4. Activate (handle both Draft and Obsolete status)
+sed -i '' 's|<status>Draft</status>|<status>Active</status>|g' "$NEW_FILE"
+sed -i '' 's|<status>Obsolete</status>|<status>Active</status>|g' "$NEW_FILE"
+
+# 5. Set schedule start date to today
+TODAY=$(date +%Y-%m-%d)
+sed -i '' "s|<startDate>[^<]*</startDate>|<startDate>${TODAY}</startDate>|g" "$NEW_FILE"
+```
+
+**What NOT to change**:
+- Namespace-prefixed references (`sales_pipe_mgmt__*`) — these remain valid in the clone
+- Action type (`getOrExecFieldUpdtSuggestion`) — preserved automatically
+- Action parameters (`recordId`, `fieldApiNames`, etc.) — preserved automatically
+- Flow elements and connectors — preserved automatically
+
+---
+
+## Step 3: Deploy the Cloned Flow
+
+```bash
+sf project deploy start --metadata "Flow:Process_Field_Update_Suggestions" --target-org $ORG --json 2>/dev/null
+```
+
+**Why deployment works**: The transformed XML is a valid Flow metadata file with:
+- Unique `<fullName>` (no conflict with template)
+- `<isTemplate>false</isTemplate>` (so it's a real flow, not a template)
+- `<status>Active</status>` (so it runs immediately)
+- All namespace-prefixed references intact (so action calls work)
+
+---
+
+## Verification
+
+```bash
+# Check that flow exists and is active — query by ApiName (reliable after a
+# Metadata-API deploy, which does NOT populate SourceTemplateId).
+sf data query -q "SELECT Id, ApiName, IsActive, SourceTemplateId FROM FlowDefinitionView WHERE ApiName='Process_Field_Update_Suggestions' AND IsTemplate=false" --target-org $ORG --json 2>/dev/null
+
+# Expected output (SourceTemplateId is typically null after a Metadata-API deploy):
+# {
+#   "status": 0,
+#   "result": {
+#     "records": [
+#       {
+#         "Id": "...",
+#         "ApiName": "Process_Field_Update_Suggestions",
+#         "IsActive": true,
+#         "SourceTemplateId": null
+#       }
+#     ],
+#     "totalSize": 1
+#   }
+# }
+```
+
+**Key indicators of success**:
+- `IsActive: true` — Flow is running
+- `totalSize: 1` — Exactly one clone named `Process_Field_Update_Suggestions`
+- `SourceTemplateId` — populated only for UI "Save As" clones; **expect `null` after a Metadata-API deploy** (does not indicate failure)
+
+---
+
+## Complete Script: Detect + Verify + Activate
+
+The PRIMARY path deploys the pre-retrieved template automatically (Method 1). This script handles detection and post-clone verification/activation; it only prompts for the Setup UI "Save As" fallback if no clone is found (i.e. the deploy was skipped or failed).
+
+```bash
+#!/bin/bash
+set -euo pipefail
+
+ORG="${1:-pipeline-mgmt-org}"
+
+echo "=== Checking if template clone already exists ==="
+CLONE_QUERY=$(sf data query -q "SELECT Id, ApiName, IsActive, SourceTemplateId FROM FlowDefinitionView WHERE SourceTemplateId='sales_pipe_mgmt__OppSuggGenSchFlow' AND IsTemplate=false" --target-org "$ORG" --json 2>/dev/null)
+
+CLONE_COUNT=$(echo "$CLONE_QUERY" | jq -r '.result.totalSize // 0')
+
+if [[ "$CLONE_COUNT" -eq 0 ]]; then
+  # Fallback: check by naming convention
+  CLONE_QUERY=$(sf data query -q "SELECT Id, ApiName, IsActive FROM FlowDefinitionView WHERE ApiName LIKE '%OppSuggGen%' AND IsTemplate=false" --target-org "$ORG" --json 2>/dev/null)
+  CLONE_COUNT=$(echo "$CLONE_QUERY" | jq -r '.result.totalSize // 0')
+fi
+
+if [[ "$CLONE_COUNT" -eq 0 ]]; then
+  echo "No template clone found."
+  echo ""
+  echo "ACTION REQUIRED: Clone the template flow manually via Setup UI:"
+  echo "  1. Setup → Flows → Find 'Process Field Update Suggestions' (template)"
+  echo "  2. Open the flow → Save As → Label: 'Process Field Update Suggestions' → Save"
+  echo "  3. Activate the new flow"
+  echo "  4. Re-run this script to verify"
+  echo ""
+  echo "NOTE: Programmatic retrieval of managed namespace flows is not possible."
+  echo "  - CLI retrieve returns: 'Entity of type Flow cannot be found'"
+  echo "  - SOAP readMetadata returns: <records xsi:nil=\"true\"/>"
+  exit 1
+fi
+
+echo "Found $CLONE_COUNT clone(s):"
+echo "$CLONE_QUERY" | jq '.result.records[] | {ApiName, IsActive, SourceTemplateId}'
+echo ""
+
+# Check if active
+IS_ACTIVE=$(echo "$CLONE_QUERY" | jq -r '.result.records[0].IsActive')
+FLOW_API_NAME=$(echo "$CLONE_QUERY" | jq -r '.result.records[0].ApiName')
+
+if [[ "$IS_ACTIVE" == "true" ]]; then
+  echo "Flow '$FLOW_API_NAME' is ACTIVE. Suggestions will generate on schedule."
+  echo ""
+  echo "=== Done ==="
+  exit 0
+fi
+
+echo "Flow '$FLOW_API_NAME' exists but is INACTIVE. Attempting activation..."
+echo ""
+
+# Activate via retrieve → transform → deploy
+sf project retrieve start --metadata "Flow:${FLOW_API_NAME}" --target-org "$ORG" --json 2>/dev/null >/dev/null || true
+
+FLOW_FILE="force-app/main/default/flows/${FLOW_API_NAME}.flow-meta.xml"
+
+if [[ -f "$FLOW_FILE" ]]; then
+  # Cross-platform sed in-place
+  if [[ "$OSTYPE" == "darwin"* ]]; then
+    sed -i '' 's|<status>Draft</status>|<status>Active</status>|g' "$FLOW_FILE"
+    sed -i '' 's|<status>Obsolete</status>|<status>Active</status>|g' "$FLOW_FILE"
+  else
+    sed -i 's|<status>Draft</status>|<status>Active</status>|g' "$FLOW_FILE"
+    sed -i 's|<status>Obsolete</status>|<status>Active</status>|g' "$FLOW_FILE"
+  fi
+
+  DEPLOY_RESULT=$(sf project deploy start --metadata "Flow:${FLOW_API_NAME}" --target-org "$ORG" --json 2>/dev/null)
+
+  if echo "$DEPLOY_RESULT" | jq -e '.status == 0' >/dev/null 2>&1; then
+    echo "Flow activated successfully via Metadata API deploy."
+  else
+    echo "Warning: Deploy returned non-zero status. Check flow in Setup → Flows."
+    echo "$DEPLOY_RESULT" | jq '.message // .result.details.componentFailures[0].problem // "unknown error"' 2>/dev/null || true
+  fi
+else
+  echo "Warning: Could not retrieve flow metadata for activation."
+  echo "Activate manually: Setup → Flows → ${FLOW_API_NAME} → Activate"
+fi
+
+echo ""
+
+# Final verification
+echo "=== Final verification ==="
+sf data query -q "SELECT ApiName, IsActive FROM FlowDefinitionView WHERE ApiName='${FLOW_API_NAME}'" --target-org "$ORG" --json 2>/dev/null | jq '.result.records[0] | {ApiName, IsActive}'
+
+echo ""
+echo "=== Done ==="
+```
+
+---
+
+## Understanding the Flow Action Type
+
+The cloned flow uses the `getOrExecFieldUpdtSuggestion` action type (NOT `generatePromptResponse`). This action:
+- Takes inputs: `recordId`, `fieldApiNames`, `agentUserId`, `agentBotDefinitionId`
+- Generates field update suggestions via prompt templates
+- Stores results as `AiGenActionItem` records (`Type = 'FIELD_UPDATE'`, `Subject` = the field API name, `ParentId` = the Opportunity Id)
+
+**Why you don't need to know this**: The template already has the correct action type configured. When you clone it, you preserve the entire action call structure — no manual construction needed.
+
+**What happens if you try to build from scratch**:
+- You'd need to know the exact action name (`getOrExecFieldUpdtSuggestion`)
+- You'd need to know the exact input parameter names and types
+- You'd need to know the namespace prefix for prompt template references
+- You'd risk getting any of these wrong and producing a non-functional flow
+
+**The clone approach avoids all of this** — the template is the source of truth.
+
+---
+
+## Namespace-Prefixed References
+
+The template flow references prompt templates with namespace prefixes:
+- `sales_pipe_mgmt__RecommendStageforOpp`
+- `sales_pipe_mgmt__RecommendNextStepforOpp`
+
+**Do NOT strip these prefixes** — they're required even in the cloned flow. The namespace prefix is how Salesforce identifies these as Pipeline Management provisioned templates (not user-created custom templates).
+
+**Why this works in the clone**: When you deploy the transformed XML with these references intact, Salesforce validates that:
+1. The referenced prompt templates exist in the org
+2. They were provisioned with the `sales_pipe_mgmt__` namespace
+3. They're active and available
+
+If you strip the namespace prefixes, the references break and the flow fails validation.
+
+---
+
+## Troubleshooting
+
+### Template doesn't exist
+
+**Symptom**: `sf project retrieve start` fails with "No source-backed components present"
+
+**Cause**: Pipeline Management is not enabled or template hasn't been provisioned yet
+
+**Fix**:
+```bash
+# Verify Pipeline Management is enabled
+curl -s "${INSTANCE_URL}/services/Soap/m/64.0" \
+  -H "Content-Type: text/xml; charset=UTF-8" \
+  -H "SOAPAction: readMetadata" \
+  -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:readMetadata>
+    <met:type>SalesDealAgentSettings</met:type>
+    <met:fullNames>SalesDealAgent</met:fullNames>
+  </met:readMetadata></soapenv:Body>
+</soapenv:Envelope>" | grep -o "<enableDealAgent>[^<]*</enableDealAgent>"
+
+# Expected: <enableDealAgent>true</enableDealAgent>
+# If false: Enable Pipeline Management first (see references/setup-order.md)
+```
+
+### Deploy fails with validation errors
+
+**Symptom**: Deploy reports errors about missing prompt templates or invalid action types
+
+**Cause**: Namespace-prefixed references were removed or template was modified incorrectly
+
+**Fix**:
+1. Re-retrieve the template (don't use a cached copy)
+2. Only transform the metadata fields listed in Step 2 — don't modify flow elements
+3. Check that namespace prefixes are intact (`grep "sales_pipe_mgmt__" "$NEW_FILE"`)
+
+### Flow deploys but doesn't run
+
+**Symptom**: Flow exists, `IsActive: true`, but no suggestions generated
+
+**Cause**: Missing prerequisites (agent not active, stage descriptions missing, no data sources)
+
+**Fix**: See `references/repair-diagnostics.md` for full checklist
+
+### Clone already exists
+
+**Symptom**: Deploy fails with "A flow with this name already exists"
+
+**Cause**: Flow was already cloned
+
+**Fix**:
+```bash
+# Check existing flow status
+sf data query -q "SELECT Id, ApiName, IsActive FROM FlowDefinitionView WHERE SourceTemplateId='sales_pipe_mgmt__OppSuggGenSchFlow' AND IsTemplate=false" --target-org $ORG --json 2>/dev/null
+
+# If IsActive: false → reactivate via Tooling API
+FLOW_ID=$(sf data query -q "SELECT Id FROM FlowDefinitionView WHERE SourceTemplateId='sales_pipe_mgmt__OppSuggGenSchFlow' AND IsTemplate=false" --target-org $ORG --json 2>/dev/null | jq -r '.result.records[0].Id')
+
+curl -X PATCH "${INSTANCE_URL}/services/data/v64.0/tooling/sobjects/Flow/${FLOW_ID}" \
+  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"Metadata":{"status":"Active"}}' 2>/dev/null
+```
+
+---
+
+## Setup UI Quick Reference (Fallback only)
+
+Deploying the pre-retrieved template (Method 1, PRIMARY) is fully automated and is what
+`scripts/create-flow.sh` / `setup-all.sh` use. The Setup UI "Save As" below is the **fallback**
+for the rare org where the programmatic deploy fails on org-specific constraints:
+
+1. Go to Setup → Flows → Find "Process Field Update Suggestions" (look for template icon)
+2. Open the flow → **Save As** → Label: "Process Field Update Suggestions" → Save
+3. **Activate** the new flow
+4. Verify: Run the detection query from "Flow Detection" section above
+
+**Limitations of the UI fallback**:
+- Requires manual interaction (not fully automatable)
+- Cannot be batched across multiple orgs via script
+- Requires System Administrator access to Setup → Flows
+
+**What is automatable after a manual fallback clone**:
+- Detection (query `SourceTemplateId` to confirm clone exists)
+- Activation (Tooling API PATCH if saved as Draft)
+- Verification (query `IsActive` status)
+- Schedule configuration (deploy modified flow XML after initial clone)
+
+---
+
+## Notes
+
+- Always use `2>/dev/null` on `sf ... --json` piped to jq
+- Flow detection uses `SourceTemplateId` (NOT label-based)
+- Clone preserves `getOrExecFieldUpdtSuggestion` action type automatically
+- Namespace-prefixed references must remain intact
+- Pipeline Management generates NO suggestions until this flow is active
+- Template is provisioned on Pipeline Management enablement but never self-activates