@salesforce/afv-skills 1.63.0 → 1.65.0

package/skills/automation-flow-coordinate/references/recipes/summarize/summarize.md

@@ -0,0 +1,323 @@
+---
+name: flow-recipe-summarize
+license: LICENSE.txt has complete terms
+description: "Use this skill to summarize a Salesforce Flow or any of its elements in plain English using the flow MCP. TRIGGER when: user says 'summarize this flow', 'summarize the X element', 'summarize Decision_1', 'what does this flow do', 'what does the [Element] do', 'explain Get_Account', 'walk me through Decision_1', 'break down the routing logic', 'I don't understand what this decision is doing', 'tell me what the [Element] does', or pastes Flow JSON, Salesforce Metadata API XML, or element JSON and asks for an explanation. Also TRIGGER for API-name and durable-version references like 'summarize Is_VIP' or 'summarize SvcCopilotTmpl__AddCaseComment-1'. DO NOT TRIGGER when: building or editing a flow (use flow-recipe-author), running tests (use flow-recipe-testing), or asking how a flow element type works in general (e.g. 'what is a Decision element' is a Salesforce-docs question, not a per-instance summary)."
+metadata:
+  version: "2.0"
+  related-skills: flow-recipe-author, flow-recipe-testing
+id: flow.recipes.summarize
+requires:
+  - flow.shared.output-format-guidelines
+  - flow.shared.flow-properties
+---
+
+# Flow & Element Summarization
+
+Plain-English explanation of what a Salesforce Flow or one of its
+elements does. **Decision** elements get the full PRD-level treatment
+(intent + path-by-path breakdown + grouping + loopback notes). All
+other element types get a tone-compliant shallow summary via the
+generic fallback. Whole-flow summaries roll up the high-level path
+skeleton and include start context only when Flow Builder exposes
+start configuration for that flow type.
+
+This recipe is **read-only**. It never writes, saves, activates,
+deactivates, or modifies a flow. It produces summary content only.
+
+## Read before you render (mandatory)
+
+This recipe is an index, not the full specification. The rules that shape the
+output live in the referenced files, not in this file. The Hard Constraints
+below are a safety net, not a substitute. Before producing any summary, open
+and read these files during the current turn:
+
+- `../../shared/output-format-guidelines.md` — always. Resolve this path from
+  this recipe's directory; it points to the shared guidance under
+  `references/shared/`.
+- `output-contract.md` — always.
+- `display.md` — always; select its matching view only after the
+  summary content passes the gates below. Determines whether output
+  is a tool call or plain Markdown based on the tool list.
+- `tone.md` — always.
+- The dispatch file for the requested summary:
+  - Whole flow → `flow-overall.md`.
+  - Decision element → `element-decision.md`.
+  - Any other element → `element-generic.md`.
+- `reference-resolution.md` § 5 — when the flow was read from the org
+  and a step you describe has a record Id or CMS content reference in
+  its inputs (a send's sender, consent subscription, or content).
+
+Do not render from this recipe's inline instructions alone. Use the retrieved
+or provided Flow metadata as the source of facts, then apply the referenced
+files as the rendering contract. If the required files have not been opened
+and read during the current turn, open them before drafting the summary.
+
+## Goal
+
+Given a FlowVersion id (`301xxx…`), a FlowDefinition id (`300xxx…`), a custom
+Flow API name, a standard Flow's namespaced durable version id, or a complete
+Flow definition as Flow JSON or Salesforce Metadata API XML, produce summary
+content that:
+
+1. Complies with `../../shared/output-format-guidelines.md` — the
+   cross-cutting suppression tiers, data-value translations, and
+   formatting defaults that apply to ALL element summaries.
+2. Conforms to the **output structure** in `output-contract.md`.
+3. Uses the deterministic render-tool or Markdown branch in
+   `display.md`.
+4. Obeys the **tone constraints** in `tone.md` (no critique, no
+   recommendations, no jargon, no raw FEROV syntax).
+5. Applies the **confidence prefix** rules in `confidence-rules.md`.
+6. Applies the **grouping rules** in `grouping.md` when a Decision has
+   13 or more paths.
+7. Handles the **edge cases** in `edge-cases.md` (empty conditions,
+   invalid values, missing downstream, etc.).
+
+If the output you are about to produce violates any of these, stop
+and re-render before showing it to the user.
+
+## When to Use This Skill
+
+Trigger on any of these phrasings (the description carries more —
+this is the short list):
+
+- "Summarize this flow" / "Summarize the [Element] decision" /
+  "Summarize Decision_1" / "Summarize Is_VIP".
+- "What does this flow do?" / "What does this decision do?" / "What
+  does Get_Account do?".
+- "Explain this flow" / "Explain Get_Account".
+- "Walk me through Decision_1" / "Break down the routing logic for
+  me" / "I don't understand what this decision is doing".
+- User pastes element JSON or flow JSON and asks for a summary.
+
+**Do not** trigger when:
+
+- The user is creating or editing a flow (route to `flow-recipe-author`).
+- The user is testing/debugging a flow (route to
+  `flow-recipe-testing`).
+- The user is asking "what is a Decision element" in general — that
+  is a docs question about the *type*, not a summary of an
+  *instance*. Defer to Salesforce documentation.
+
+## Routing
+
+Six steps, in order. Do not skip step 1.
+
+### Step 1 — Resolve the available summary context
+
+Whole-flow context is preferred because it enables downstream-element
+labels, formula expressions, FEROV references, and loopback detection.
+An element-only definition is still valid input; summarize it with the
+documented low-confidence limitations. See `reference-resolution.md`
+for the full ladder. Short version:
+
+| Input you have | What to do |
+|---|---|
+| `301xxx…` (FlowVersion id) | Call `dispatch_readonly(method: "GET", url: "/services/data/vXX.0/flowbuilder/flow/<id>")` directly. |
+| `300xxx…` (FlowDefinition id) | Call `dispatch_readonly(method: "GET", url: "/services/data/vXX.0/flowbuilder/flow/<id>")` directly. The tool resolves the Active version, or the latest version when none is Active; do not make a separate version-list call. |
+| Custom Flow API name (e.g. `Lead_Routing` or `acme__Lead_Routing`) | Call `dispatch_readonly(method: "GET", url: "/services/data/vXX.0/flowbuilder/flow/<id>")` with the exact API name. The tool resolves the Active version, or the latest version when none is Active. Do not translate labels, add/remove a namespace, or make a separate version-list call. |
+| Standard Flow namespaced durable version id (e.g. `SvcCopilotTmpl__AddCaseComment-1`) | Call `dispatch_readonly(method: "GET", url: "/services/data/vXX.0/flowbuilder/flow/<id>")` with the exact durable id. The `-N` suffix selects that standard Flow version. |
+| Flow label (e.g. `Lead Routing`) | A label is not a supported `GET /services/data/vXX.0/flowbuilder/flow/{id}` identifier. Ask for the exact API name, a `301xxx…` FlowVersion id, or the complete Flow definition as Flow JSON or Salesforce Metadata API XML. Do not convert spaces to underscores or otherwise guess an API name. |
+| Element definition pasted as Flow JSON or Salesforce Metadata API XML, no flow context | Summarize from the element only and apply the low-confidence prefix; loopback and downstream labels will be unresolved |
+| Complete Flow definition pasted as Flow JSON or Salesforce Metadata API XML | Use directly for read-only summarization; no MCP call needed |
+
+If resolution fails (no metadata returned, session expired, or the referenced
+flow does not exist), stop and report the failure plainly. Ask the user to
+provide one of these supported inputs:
+
+1. The exact custom Flow API name, including its namespace when applicable.
+2. The standard Flow's namespaced durable version id, including its `-N`
+   version suffix.
+3. The FlowVersion id (the `301…` id) or FlowDefinition id (the `300…` id).
+4. The complete Flow definition as either Flow JSON or Salesforce Metadata API
+   XML.
+
+Metadata API XML is accepted as read-only summarization input only. Do not pass
+XML to save operations, which require the Flow MCP JSON schema.
+Never invent metadata.
+
+### Step 2 — Decide flow vs. element
+
+- User asked about **the flow as a whole** ("summarize this flow",
+  "what does this flow do") → open and read `flow-overall.md`, then
+  render to its contract. Do not free-form the summary directly from
+  the Flow metadata retrieved in step 1.
+- User named **a single element** ("summarize Decision_1", "what does
+  Get_Account do") → continue to step 3.
+- User pasted **a single element JSON** with no broader request →
+  continue to step 3.
+- Ambiguous (multiple Decisions exist and user said "summarize the
+  decision") → ask one disambiguation question. Do not guess.
+
+### Step 3 — Locate the target element
+
+Find it by `name` (API name) first, then `label`. If multiple
+elements share the same label, ask which one the user meant. If no
+match, say so and list the element names that *do* exist.
+
+### Step 4 — Dispatch by element type
+
+| Element `type` in metadata | Reference to load |
+|---|---|
+| `Decision` | `element-decision.md` (full PRD treatment) |
+| any other type | `element-generic.md` (shallow but tone-compliant) |
+
+Open and read the dispatched file before rendering. The inline Hard
+Constraints below are not a substitute for its complete contract.
+
+`element-record-lookup.md`, `element-record-create.md`,
+`element-record-update.md`, `element-record-delete.md` are reserved
+for P1 — they do not exist yet. Until they do, CRUD elements route
+to `element-generic.md`.
+
+### Step 5 — Build and validate summary content
+
+Apply, in order:
+
+1. Remove every Flow-level and element-level `description` field from
+   the facts available for drafting. Derive intent only from configured
+   Start behavior, elements, connectors, conditions, assignments, and
+   values. If an intent clause cannot be traced to that configuration,
+   delete it. Do not name an actor, persona, caller, or beneficiary (for
+   example, a customer, agent, or administrator) unless that role is
+   explicitly represented by a configured Screen, action, condition, or
+   record relationship.
+2. For a Screen Flow or non-triggered Autolaunched Flow, remove all
+   `variables[]` entries with `isInput: true` from the summary input
+   before interpreting references. When an element references one of
+   those variables, resolve only the target's business role from the
+   element/object context (for example, "the case being handled");
+   never reveal the variable, its value, its source, or invocation
+   context. In the final draft, replace any source-implying use of
+   "given," "provided," "supplied," "passed-in," or "input" with the
+   value's business noun, such as "the comment text."
+3. The suppression tiers from `../../shared/output-format-guidelines.md`
+   (Tier 1 items removed unconditionally; Tier 2 items translated;
+   data values humanized; formatting defaults enforced).
+4. The shape from `output-contract.md`.
+5. The grouping rules from `grouping.md` (Decision only, when path
+   count ≥ 13).
+6. The confidence prefix from `confidence-rules.md`.
+7. The tone constraints from `tone.md` — read this last, because it
+   is also the gate that blocks output.
+
+Cross-check the rendered output against the closest example in
+`examples/`. If your output diverges materially from every example,
+something is wrong with the rendering — fix before showing.
+
+When a render tool will be used, apply this example gate to the text
+inside `detailedSummary` and `shortSummary`, not to the tool-call
+envelope.
+
+### Step 6 — Deliver
+
+Open `display.md` and use exactly one matching view:
+
+- Whole-flow summary → `display.md` §"summarize-flow".
+- Single-element summary → `display.md` §"summarize-element".
+
+The view's guarded rules decide tool call vs. plain Markdown.
+
+### Before you show the output (gate)
+
+Confirm every item below is true. If any item is false, stop and fix it:
+
+- You opened and read `../../shared/output-format-guidelines.md`,
+  `output-contract.md`, `display.md`, and `tone.md` during the current
+  turn.
+- You opened and read the dispatch file for this request
+  (`flow-overall.md`, `element-decision.md`, or `element-generic.md`) and
+  rendered to its contract.
+- You checked the tool list for the current turn against `display.md`
+  and chose the matching view per its guarded rules.
+- The summary content matches the closest applicable file in
+  `examples/`. In tool-call mode, check the summary parameter values
+  rather than the tool envelope.
+
+If the draft was produced from this recipe's inline instructions without
+opening those files, discard it and re-render from the referenced contracts.
+
+## Hard Constraints
+
+These are violations that automatically reject the output. Each is
+expanded with reasoning in `tone.md` and
+`../../shared/output-format-guidelines.md`.
+
+Exception: **if a matching tool is in the tool list** for this
+summary type, call it instead of emitting plain text. See `display.md`
+for the guarded views, parameter contract, schema compatibility, and
+the plain-Markdown fallback used when no such tool is present or a
+call fails. The tool call itself is not a violation of the constraints
+below — but they still apply in full to the text inside each parameter
+value.
+
+Tools are an internal detail of how the recipe produces output.
+Never name a tool, name its parameters, state which branch (tool
+call or plain text) was taken, or narrate the detection step — in
+either branch. Never emit a preamble, framing sentence, or
+disclaimer before the summary. The first character of the response
+is the first character of the summary. Return the summary, not an
+account of producing it.
+
+- **Tier 1 suppression (unconditional).** Never show GUIDs/UUIDs,
+  canvas coordinates (x/y), internal system timestamps
+  (SystemModstamp, LastModifiedById), raw JSON/XML payloads, or
+  Salesforce version tokens/etags. If a user asks for one, politely
+  note it's not useful and offer to summarize instead.
+- **No critiques.** Never write "consider", "should", "may want to",
+  "appears unreachable", "largely unreachable in practice", "is
+  fine", "no error, no log, no fault", or any other evaluative
+  language. State what the configuration *does*, not whether it is
+  good.
+- **No recommendations.** Do not propose changes, alternatives, or
+  improvements.
+- **No raw condition syntax.** `StageName == "Closed Won"` becomes
+  "Stage is Closed Won". If the user explicitly asks for raw syntax,
+  show it alongside (never instead of) the plain-English
+  translation.
+- **No FEROV literals shown.** A `booleanValue: false` or
+  `numberValue: 100000` is rendered as plain English ("is not
+  active", "exceeds $100,000"). Booleans are rendered contextually
+  ("is active" / "is not active", "is checked" / "is unchecked") —
+  never literal `true`/`false`.
+- **No element-type explainer.** Do not explain what a Decision
+  element *is* in general; describe only what *this* one does.
+- **No description-field content.** Flow and element descriptions are
+  excluded from input (PRD §2.2 footnote — descriptions are
+  frequently stale and unreliable).
+- **No markdown tables in output.** Use bullet lists. Tables are
+  acceptable only if the user explicitly requests a comparison or
+  table layout.
+- **No code blocks or backtick formatting.** Write values in plain
+  text with quotation marks (e.g., Stage is "Closed Won").
+  Acceptable only if user explicitly asks for code output.
+- **Null/empty → human text.** Render as "not set," "no value
+  configured," or "blank." Never write `null`, `""`, or similar
+  literally.
+- **No inapplicable start context.** For Screen Flows and
+  non-triggered Autolaunched Flows, never summarize the trigger or
+  launch type, entry conditions, or flow-level input variables. Do
+  not render empty-state statements for them and do not move them
+  into the intent or path text. See
+  `../../shared/output-format-guidelines.md` §"Flow-Type Start-Context
+  Suppression."
+- **Default path is always the final bullet** in a path list, and
+  labeled as the fallback for "all other cases" / "records that
+  don't match any of the above conditions".
+
+## Reference Index
+
+| File | When to consult |
+|---|---|
+| `../../shared/output-format-guidelines.md` | Every render — suppression tiers, data translations, formatting defaults |
+| `output-contract.md` | Every render — defines output structure |
+| `display.md` | Every render — selects the tool call or Markdown fallback |
+| `tone.md` | Every render — defines what cannot appear |
+| `confidence-rules.md` | When deciding to prefix with "It appears that" |
+| `grouping.md` | Decision with 13+ paths |
+| `edge-cases.md` | Empty/invalid conditions, missing downstream, duplicate logic |
+| `reference-resolution.md` | Translating ids, FEROVs, formulas, downstream labels |
+| `element-decision.md` | Element type = Decision (MVP) |
+| `element-generic.md` | Any non-Decision element type |
+| `flow-overall.md` | Whole-flow summary requests |
+| `examples/*.md` | Quality-bar reference; cross-check final output |

package/skills/automation-flow-coordinate/references/recipes/testing/examples/debug-output-template.md

@@ -0,0 +1,109 @@
+# Debug — Headline Output Template
+
+Verbatim skeleton and worked example for the **Headline** layer emitted by every run in `[[flow.recipes.testing.workflows.debug]]` Phase 2 → Loop body → step 2. Copy the skeleton exactly — same headers, same order, every section present even if a section is `None` (the one exception is `### Paused`, which appears only while a run is paused). Do not paraphrase headers, merge sections, or reorder.
+
+## Headline skeleton (copy verbatim, fill in per run)
+
+```markdown
+### Summary
+<One paragraph, business language. What the execution did end-to-end. No element-by-element narration. No `interviewId`, no debug log line numbers, no Aura wire shape.>
+
+### Paused
+<Emit ONLY while the run is paused (`interviewStatus` is `WAITING` or `ASYNC_WAITING`); omit this whole section otherwise. State the Wait element the run stopped at, then one bullet per entry in `waitEvents[]`: the event `name` and its resume time (`value`), or "platform event" when `value` is empty.>
+
+### Inputs
+<Bulleted list of the inputs that drove this run: `$Record` value / input variables / scheduled path / trigger context. One bullet per input. `None` if the flow takes no inputs.>
+
+### Outputs
+<Bulleted list of output variables and their final values. `None` if the flow has no output variables.>
+
+### Governor limits
+<Bulleted list of any governor-limit-relevant counters that were exercised (SOQL queries, DML rows, CPU time, etc.). `None if not applicable` for this flow shape.>
+
+### What's next?
+Deep dive into execution details? Refine inputs? Try a different scenario? Or save this run as a test?
+
+Is there a specific part of the trace you'd like to focus on?
+```
+
+## Paused and resumed runs
+
+- **`### Paused` is the one conditional section.** Every other section stays present even when its value is `None`. Place `### Paused` directly after `### Summary`.
+- **While paused, replace the "What's next?" first line** with: `Resume at which wait event? Refine inputs? Or try a different scenario?` Saving as a test is not offered mid-pause.
+- **After a resume, keep one cumulative headline.** `### Summary` covers the run so far, and the trace is the original legs plus the resumed leg. Do not emit a second, separate headline for the resumed leg.
+- **When the resumed run finishes, drop `### Paused`** and use the normal "What's next?" text. If the user then saves, the run can only be saved as a test without assertions.
+
+## Worked example (record-triggered flow on `Account`, one update, no faults)
+
+```markdown
+### Summary
+The flow ran on Account `001XX000003DHPq` after an update. It evaluated the entry condition (`Rating` changed to `Hot`), then routed through the `Notify Owner` branch and queued a task assignment for the record owner. No fault paths taken; the flow completed successfully.
+
+### Inputs
+- `$Record`: Account `001XX000003DHPq` (Name: "Acme Corp", Rating: `Hot`, prior Rating: `Warm`)
+- Trigger context: `RecordAfterSave`, update
+
+### Outputs
+- `taskCreated`: `true`
+- `assignedTo`: `005XX000001Sv8YQAS`
+
+### Governor limits
+- SOQL queries: 1 / 100
+- DML rows: 1 / 10,000
+
+### What's next?
+Deep dive into execution details? Refine inputs? Try a different scenario? Or save this run as a test?
+
+Is there a specific part of the trace you'd like to focus on?
+```
+
+## Worked example (autolaunched flow paused at a Wait, then resumed)
+
+First leg — the run stops at the Wait:
+
+```markdown
+### Summary
+The flow started with `accountId` set to `001XX000003DHPq`, updated the account's Rating to `Hot`, and then stopped at the `Wait_For_Approval` element. It has not finished yet.
+
+### Paused
+The run is waiting at `Wait_For_Approval`. Resumable wait events:
+- `Approved_Event`: resumes at 2026-10-14T09:00:00Z
+- `Rejected_Event`: platform event
+
+### Inputs
+- `accountId`: `001XX000003DHPq`
+
+### Outputs
+None
+
+### Governor limits
+- SOQL queries: 1 / 100
+- DML rows: 1 / 10,000
+
+### What's next?
+Resume at which wait event? Refine inputs? Or try a different scenario?
+
+Is there a specific part of the trace you'd like to focus on?
+```
+
+After resuming on `Approved_Event` — one cumulative headline, no `### Paused`:
+
+```markdown
+### Summary
+The flow updated the account's Rating to `Hot`, waited at `Wait_For_Approval`, and after resuming on `Approved_Event` created a follow-up task for the owner. It then completed successfully.
+
+### Inputs
+- `accountId`: `001XX000003DHPq`
+
+### Outputs
+- `taskCreated`: `true`
+
+### Governor limits
+- SOQL queries: 2 / 100
+- DML rows: 2 / 10,000
+
+### What's next?
+Deep dive into execution details? Refine inputs? Try a different scenario? Or save this run as a test?
+
+Is there a specific part of the trace you'd like to focus on?
+```

package/skills/automation-flow-coordinate/references/recipes/testing/shape.md

@@ -0,0 +1,219 @@
+# FlowTest definition — shape
+
+The `flowTest` object below (`fullName` + `metadata`) is the FlowTest
+**definition** shared by `POST /services/data/vXX.0/flowbuilder/flow-test`, `PATCH /services/data/vXX.0/flowbuilder/flow-test/{id}`, and
+`POST /services/data/vXX.0/flowbuilder/flow-test/debug-interview-test-mode`. It is the **inner** shape, not the wire
+body: each endpoint takes it as a JSON-encoded **string** in `flowTestJson`
+(`flowTestJson: JSON.stringify(flowTest)`). `POST /services/data/vXX.0/flowbuilder/flow-test/debug-interview` does not
+consume this shape; it is argument-driven (`flowVersionId` plus ad-hoc
+`arguments`). This page is the **top-level skeleton**: the definition, the
+`testPoints[]` frame, and the cross-cutting save/round-trip truths. The
+per-element detail lives in dedicated files, linked inline below —
+this file is the map, not the territory.
+
+If you are mapping a debug run into a saved test, also read
+[[flow.recipes.testing.workflows.promote]] — that file explains the
+*workflow*; this file explains the *schema*.
+
+## Wire format
+
+### Top-level fields
+
+```jsonc
+{
+  "fullName": "<flowApiName>_<scenario_slug>",   // server-validated identifier
+  "metadata": {
+    "label": "<human-facing name>",              // shown in the Tests panel
+    "description": "<optional>",
+    "flowApiName": "<flow API name>",            // must match the parent flow
+    "flowTestFlowVersions": [                    // versions this test runs against
+      { "flowVersionNumber": "2" },
+      { "flowVersionNumber": "1" }
+    ],
+    "testType": "WithAssertion",                 // or "WithoutAssertion"
+    "testPoints": [ /* see below */ ],
+    "flowTestDataSources": [],                   // Apex @testSetup bindings
+    "isolatedObjectExternalKeys": [],            // silo external keys — usually []
+    "doesCommitChanges": false,                  // false = roll DML back on rerun
+    "doesSkipStartConditions": false,            // true = bypass entry criteria
+    "doesTestWaitElement": false,                // true = actually wait at Wait elements
+    "isSubflowUseLatestFlowVer": false           // canonicalized on save (default false)
+  }
+}
+```
+
+| Field | Notes |
+|---|---|
+| `fullName` | Conventionally `<FlowApiName>_<scenario_slug>`. Must be unique within the flow. Server-validated. |
+| `flowTestFlowVersions[]` | Each entry pins the test to one version number. A single test can run across several versions — e.g. `[{"flowVersionNumber":"2"},{"flowVersionNumber":"1"}]`. Versions are strings, not numbers. |
+| `testType` | `WithAssertion` if any element has a non-empty `assertions[]`; otherwise `WithoutAssertion`. The two values and the coupling rule live in [[flow.recipes.testing.flowtest-elements.assertions]]. `WithoutAssertion` binds record-typed inputs by `Id`, with extra fields allowed only on the Updated snapshot — see [[flow.recipes.testing.flowtest-elements.parameters]] § "Record-typed inputs on `WithoutAssertion`". |
+| `doesCommitChanges` | Almost always `false` for regression tests. Flip to `true` only when downstream effects (e.g. outbound message side effects) cannot be observed without persisted state. |
+| `doesSkipStartConditions` | `true` lets you exercise a flow without satisfying its trigger entry filter — handy for scenarios where the trigger criteria are orthogonal to what you're testing. |
+| `doesTestWaitElement` | `true` makes Wait elements actually pause when the test is replayed; `false` skips the wait so the run completes synchronously. Use `false` for `WithAssertion` tests (the runner cannot resume a paused interview). `true` suits a `WithoutAssertion` test saved from a paused debug run. For non-Wait flows the wire value is `false`. |
+| `flowTestDataSources[]` | Binds silo fixture data (`AiGenerated` mock records or an Apex `@testSetup` class) that seed the Flow Test silo at run time. Default `[]` means no silo. Full shape, discovery tools, and the `jsonValue` binding it switches on: [[flow.recipes.testing.flowtest-elements.silo-config]]. |
+| `isolatedObjectExternalKeys[]` | The identity bridge between the trigger record and the silo's seeded fixtures. Default `[]`. See [[flow.recipes.testing.flowtest-elements.silo-config]]. |
+
+### `testPoints[]`
+
+An array, one entry per element that needs scripted input or an
+expectation. In practice the only entries you will see are:
+
+- One on `Start` — supplies the trigger record (and, for update flows,
+  the "after" snapshot and/or the scheduled-path pick).
+- Optionally one on `Finish` — to bind assertions to "did the flow take
+  the right path / leave records in the right state".
+
+Each entry:
+
+```jsonc
+{
+  "elementApiName": "Start",          // canvas element API name
+  "parameters": [ /* inputs */ ],     // bind values into element
+  "assertions": [ /* expectations */ ], // check values after element runs
+  "isUseMockOutput": false            // canonicalized on save (default false)
+}
+```
+
+The per-shape detail is split out:
+
+- **`parameters[]`** — the typed value envelope and the
+  `FlowTestParameterType` slots: [[flow.recipes.testing.flowtest-elements.parameters]].
+  Binding the trigger record by flow type:
+  [[flow.recipes.testing.flowtest-elements.parameters]].
+- **`assertions[]`** — element-level vs. value operators, `errorMessage`,
+  and the AND semantics: [[flow.recipes.testing.flowtest-elements.assertions]].
+- **`testPoints[]` placement and `isUseMockOutput`** —
+  [[flow.recipes.testing.flowtest-elements.test-points]].
+
+### How the pieces assemble — minimal examples
+
+A `WithoutAssertion` save (`Update_Account_Name_To_BAC`) — just inputs,
+no expectation. Note the Id-only `sobjectValue`: on `WithoutAssertion`
+tests, record-typed inputs are bound by `Id`. The one exception is the
+Updated snapshot on before/after-update flows, which carries `Id` plus
+the changed fields. See
+[[flow.recipes.testing.flowtest-elements.parameters]] § "Record-typed
+inputs on `WithoutAssertion`" for the full per-slot rule.
+
+```json
+{
+  "fullName": "Update_Account_Name_To_BAC_TEMP_20260521_save_as_test_try1",
+  "metadata": {
+    "label": "save as test try1",
+    "description": "",
+    "flowApiName": "Update_Account_Name_To_BAC_TEMP_20260521",
+    "flowTestFlowVersions": [{ "flowVersionNumber": "1" }],
+    "testType": "WithoutAssertion",
+    "testPoints": [
+      {
+        "elementApiName": "Start",
+        "parameters": [
+          {
+            "leftValueReference": "$Record",
+            "value": { "sobjectValue": "{\"Id\":\"001SM000001TNFCYA4\"}" },
+            "type": "InputTriggeringRecordInitial"
+          },
+          {
+            "leftValueReference": "ScheduledPathApiName",
+            "value": { "stringValue": "" },
+            "type": "ScheduledPath"
+          }
+        ],
+        "assertions": []
+      }
+    ],
+    "flowTestDataSources": [],
+    "isolatedObjectExternalKeys": [],
+    "doesCommitChanges": false,
+    "doesSkipStartConditions": false
+  }
+}
+```
+
+A `WithAssertion` save (`brandNewTest`) — full trigger record on
+`Start`, plus a `Finish`-element assertion that `Set_Name_To_BAC` was
+visited:
+
+```json
+{
+  "fullName": "brandNewTest",
+  "metadata": {
+    "label": "brandNewTest",
+    "description": "",
+    "flowApiName": "Update_Account_Name_To_BAC_TEMP_20260521-2",
+    "flowTestFlowVersions": [
+      { "flowVersionNumber": "2" },
+      { "flowVersionNumber": "1" }
+    ],
+    "testType": "WithAssertion",
+    "testPoints": [
+      {
+        "elementApiName": "Start",
+        "parameters": [
+          {
+            "leftValueReference": "$Record",
+            "value": {
+              "sobjectValue": "{\"AccountNumber\":\"CD656092\",\"Name\":\"Burlington Textiles Corp of America\",\"BillingCity\":\"Burlington\",\"BillingState\":\"NC\",\"Industry\":\"Apparel\",\"Type\":\"Customer - Direct\"}"
+            },
+            "type": "InputTriggeringRecordInitial"
+          }
+        ],
+        "assertions": []
+      },
+      {
+        "elementApiName": "Finish",
+        "parameters": [],
+        "assertions": [
+          {
+            "conditions": [
+              {
+                "leftValueReference": "Set_Name_To_BAC",
+                "operator": "WasVisited",
+                "rightValue": { "booleanValue": true }
+              }
+            ]
+          }
+        ]
+      }
+    ],
+    "flowTestDataSources": [],
+    "isolatedObjectExternalKeys": []
+  }
+}
+```
+
+## Constraints
+
+### Source-of-truth principle: round-trip, don't guess
+
+Hand-written or example payloads are starting points, not authority.
+The Aura wire format normalizes shapes — string-form numbers come back
+as JSON numbers, optional fields appear with default values, etc.
+**When in doubt, save once with `POST /services/data/vXX.0/flowbuilder/flow-test`/`PATCH /services/data/vXX.0/flowbuilder/flow-test/{id}` and
+reload with `GET /services/data/vXX.0/flowbuilder/flow-test/{id}`** — parse the returned `flowTestJson` string;
+that decoded definition is the canonical form for that org/release.
+Update this file when a round-trip shows something the prose doesn't cover.
+
+Worth knowing up front from probe runs:
+
+- `POST /services/data/vXX.0/flowbuilder/flow-test`/`PATCH /services/data/vXX.0/flowbuilder/flow-test/{id}` run **deep server-side validation** on
+  save. A malformed payload — bad `type` enum, mismatched value
+  envelope, a `leftValueReference` that doesn't resolve to a flow
+  resource or element, duplicate test points, a missing required
+  parameter — can come back `isSuccess: false` with optional `errors[]`
+  details. Fix a field only when a message identifies it; otherwise
+  surface the raw response. Don't pre-check against a memorized rule list.
+  A confirmed `isSuccess === true` response means the
+  payload is well-formed and every reference resolves — but still run the
+  test, because save cannot verify that an assertion's *expected value*
+  is the one you meant (a semantically-valid-but-wrong expectation saves
+  clean and only fails when run).
+- `numberValue` accepts both `"40"` and `40` on save but the canonical
+  form is the unquoted JSON number. Round-trip will normalize.
+- The `value` envelope always carries `collectionElements: []` after
+  canonicalization. Omitting it on save is fine; the server fills it.
+
+> **Field discovery via round-trip.** Both `doesTestWaitElement` and
+> `isSubflowUseLatestFlowVer` were discovered by saving a minimal
+> payload and parsing `GET /services/data/vXX.0/flowbuilder/flow-test/{id}.flowTestJson`. When the
+> docs feel incomplete, save a probe and reload.