@salesforce/afv-skills 1.37.0 → 1.38.0

package/skills/agentforce-generate/references/agent-script-core-language.md

@@ -21,7 +21,7 @@
 
 Agent Script operates in two phases: deterministic resolution, then LLM reasoning.
 
-**Phase 1: Deterministic Resolution.** The runtime executes a subagent's reasoning instructions top to bottom — evaluating `if`/`else` conditions, running actions via `run`, and setting variables via `set`. The LLM is NOT involved yet. The runtime builds a prompt string by accumulating `|` pipe text and resolving conditional logic. If a `transition` command occurs, the runtime discards the current prompt and starts fresh with the target subagent.
+**Phase 1: Deterministic Resolution.** The runtime executes a subagent's reasoning instructions top to bottom — evaluating `if`/`else` conditions, running actions via `run`, and setting variables via `set`. The LLM is NOT involved yet. The runtime builds a prompt string by accumulating `|` pipe text and resolving conditional logic. If a `transition` command occurs, the current subagent stops resolving and the target subagent begins its lifecycle with shared state and conversation history retained.
 
 **Phase 2: LLM Reasoning.** The runtime passes the resolved prompt to the LLM along with any reasoning actions (tools) the subagent exposes. The LLM decides what to do — it can call available actions but cannot modify the prompt text. It only reasons against what Phase 1 resolved.
 
@@ -36,8 +36,8 @@ subagent check_order:
                     with id = @variables.order_id
                     set @variables.status = @outputs.status
 
-            | Your order status is {!@variables.status}.
-              You can modify it using the {!@actions.update_order} action.
+            | Tell the user the exact order status is {!@variables.status} and
+              use {!@actions.update_order} for a requested modification.
 
         actions:
             update: @actions.update_order
@@ -53,7 +53,9 @@ You can modify it using the update_order action.
 
 The LLM then receives this prompt plus the `update` tool and decides whether to call it based on what the user asks.
 
-This split is critical: **deterministic logic controls WHAT the agent knows (via resolved prompt), and the LLM controls WHETHER and HOW to act on that knowledge**.
+This split is critical: **deterministic resolution controls which authored
+prompt text and tools reach the planner; the LLM chooses its text and
+model-selected actions within that resolved context**.
 
 ---
 
@@ -96,14 +98,21 @@ subagent my_subagent:
 
 **Note:** The compiler does not enforce top-level block ordering. Use the order above when generating new files, but do not reorder existing files that use a different order — they are equally valid.
 
+This page is a practical authoring reference, not an exhaustive schema for
+every supported compiler or target version. In repair work, do not delete an
+existing construct merely because an abbreviated list or example on this page
+omits it. Preserve accepted constructs unless the selected compiler, target-org
+validator, or concrete runtime evidence identifies a defect.
+
 **Within `start_agent` and `subagent` blocks**, the internal ordering is:
 
-1. `description` (required)
-2. `system` (optional — subagent-level override of global system instructions)
-3. `before_reasoning` (optional — runs before reasoning phase)
-4. `reasoning` (required)
-5. `after_reasoning` (optional — runs after reasoning phase)
-6. `actions` (optional — action definitions)
+1. `label` (optional human-readable display name)
+2. `description` (required)
+3. `system` (optional — subagent-level override of global system instructions)
+4. `before_reasoning` (optional — runs before reasoning phase)
+5. `reasoning` (required)
+6. `after_reasoning` (optional — runs after reasoning phase)
+7. `actions` (optional — action definitions)
 
 ---
 
@@ -234,9 +243,21 @@ system:
         error: "Sorry, something went wrong. Please try again."
 ```
 
+The selected global or subagent `system.instructions` value is rendered on
+each reasoning iteration and may contain merge fields such as
+`{!@variables.account_status}`. It is declarative prompt text, not a procedure:
+do not use `instructions: ->`, `run`, `set`, `if`, or `transition` inside a
+system block. Put deterministic procedures in the supported lifecycle or
+reasoning procedure blocks. Interpolation exposes a current value to the
+model; it does not make the model's use of that value deterministic.
+
 The `instructions` field is required and contains text directives sent to the LLM in every reasoning phase. Subagent-level system blocks can override this.
 
-Both `welcome` and `error` messages are required.
+The `messages` block is optional. When a target or use case requires custom
+welcome or error copy, define the relevant messages and validate them against
+that target. Do not add messages, rewrite an existing instruction scalar, or
+change tone during a bounded repair without an accepted finding tied to an
+affected use case.
 
 **Access and config blocks** contain runtime identity and agent metadata:
 
@@ -251,13 +272,15 @@ config:
     agent_type: "AgentforceServiceAgent"
 ```
 
-The `access:` form is covered by this repository's pinned
-[AgentScript toolchain floor](../../../tests/agentscript-toolchain.json).
-Public npm packages and target-org compilers can lag; validate against the
-deployment org before release.
+The `access:` form is covered by the compiler workflow in
+[AgentScript Compiler Setup](agentscript-toolchain.md). Public npm packages,
+public source, and target-org compilers can differ; record the local provider
+and validate against the deployment org before release.
 
 **Required fields:**
 - `developer_name` (NOT `agent_name`) — unique identifier following naming rules. Must exactly match the AiAuthoringBundle directory name (e.g., if the directory is `aiAuthoringBundles/Travel_Advisor/`, then `developer_name` must be `"Travel_Advisor"`). A mismatch causes deploy failures.
+
+**Recommended explicit field for newly authored bundles:**
 - `agent_type` — `"AgentforceServiceAgent"` or `"AgentforceEmployeeAgent"`. Determines deployment context and whether `default_agent_user` is required:
   - `"AgentforceServiceAgent"` — customer-facing, deployed via messaging channels. **Requires `default_agent_user`** with Einstein Agent license.
   - `"AgentforceEmployeeAgent"` — internal employee-facing. Agent Script files with this agent type MUST NOT include:
@@ -266,6 +289,14 @@ deployment org before release.
     - Escalation subagent with `@utils.escalate`
     - `connection messaging:` block
 
+  Existing bundles and compiler versions can accept an omitted `agent_type`;
+  some environments apply a default. Do not add or change it during a bounded
+  repair merely to complete the schema. Require a target diagnostic or a
+  user-declared deployment context, and do not infer employee versus service
+  type from wording or from the absence of channel-specific constructs alone.
+  When creating a new bundle, set it explicitly and validate the related
+  access and connection contracts against the target org.
+
   **Common mistake — service-agent constructs on employee agent:**
 
   ```agentscript
@@ -392,6 +423,7 @@ In prompt text (inside `|` pipe sections), always use `{!@variables.X}` with bra
 
 ```agentscript
 subagent order_lookup:
+    label: "Order Lookup"
     description: "Handle customer order inquiries"
 
     reasoning:
@@ -413,6 +445,11 @@ subagent order_lookup:
 
 **Description is required** — the LLM uses this to understand when the subagent is relevant.
 
+**Label is optional** — use `label` on `start_agent` or `subagent` when a
+human-readable display name is useful. It is distinct from top-level
+`config.agent_label`. Preserve an existing `label` during repair unless the
+selected compiler or deployment target rejects it.
+
 **Subagent-level system override** (optional) — replaces global system
 instructions for this subagent and does not merge with them. Omit the override
 when global instructions should remain intact. If an override is necessary,
@@ -431,12 +468,13 @@ subagent product_specialist:
 
 **Internal block ordering within a subagent**:
 
-1. `description`
-2. `system` (optional override)
-3. `before_reasoning` (optional)
-4. `reasoning` (required)
-5. `after_reasoning` (optional)
-6. `actions` (optional definitions)
+1. `label` (optional display name)
+2. `description`
+3. `system` (optional override)
+4. `before_reasoning` (optional)
+5. `reasoning` (required)
+6. `after_reasoning` (optional)
+7. `actions` (optional definitions)
 
 **Before/after reasoning directive blocks**:
 
@@ -464,9 +502,10 @@ Directive blocks use the arrow syntax (`->`) for logic but no LLM reasoning. The
 
 Reasoning instructions combine deterministic logic and prompt text. The runtime resolves deterministic parts first, then sends the resulting prompt to the LLM for reasoning.
 
-The resolved prompt is rebuilt on every reasoning iteration, including after a
-tool call updates variables. Keep it short and task-local: current objective,
-relevant state, action guidance, exclusions, and stop conditions. Keep persona,
+The resolved prompt is rebuilt for every reasoning iteration. A completed tool
+batch normally leads to another iteration unless execution hands off, pauses,
+is cancelled, or reaches a limit. Keep the prompt short and task-local: current
+objective, relevant state, action guidance, exclusions, and stop conditions. Keep persona,
 tone, disclosure, safety, and broad scope rules in the effective system layer.
 Treat effective system and reasoning text as cumulative unless the target
 runtime's public, versioned contract guarantees different precedence, so the
@@ -529,50 +568,56 @@ instructions: ->
         | Suggest self-service options.
 ```
 
-Within `->` blocks, a line without `|` continues the previous line. A new `|` starts a new line:
+Within `->` blocks, a line without `|` continues the current prompt fragment.
+Use one `|` per contiguous block and align continuation lines beneath its
+content:
 
 ```agentscript
 instructions: ->
     | This is a long instruction that
       continues on the next physical line.
-    | This starts a new logical line.
+      This remains part of the same prompt block.
 ```
 
+Start another `|` after a runtime statement or conditional boundary when a new
+prompt fragment is structurally required. Repeating `|` on every adjacent
+sentence is valid syntax, but it does not create steps or control flow.
+
 ### Conditional Control Flow Syntax
 
-Use `if / else if / else` for one mutually exclusive chain:
+When authoring a new two-way branch whose alternatives are exclusive, prefer
+`if / else`:
 
 ```agentscript
-# Supported multi-branch chain
 if @variables.count < 5:
     run @actions.small
-else if @variables.count < 10:
-    run @actions.medium
 else:
     run @actions.large
+```
 
-# Invalid legacy spelling
+For three or more alternatives where exactly one branch should run, use an
+`if / else if / else` chain. The first matching branch wins:
+
+```agentscript
 if @variables.count < 5:
     run @actions.small
-elif @variables.count < 10:
+else if @variables.count < 10:
     run @actions.medium
+else:
+    run @actions.large
 ```
 
-`else if` is supported and may repeat before the optional final `else`. `elif`
-is not an AgentScript keyword and produces a syntax error.
+Spell the clause `else if`; Python-style `elif` is not valid AgentScript. Do not
+place a separate `if` inside a conditional body: true user-written nested
+conditionals are unsupported. Combine predicates with `and` or `or`, or use an
+`else if` chain.
 
-This conditional form is covered by the repository's pinned
-[AgentScript toolchain floor](../../../tests/agentscript-toolchain.json).
-Run target-org validation before release because org compilers can lag the
-open-source toolchain.
-
-Do not place an `if` inside another conditional body. Agentforce lint rejects
-user-written nested conditionals with the `unsupported-nested-if` error. The
-compiler also warns for nested `if/else` because its condition slot is shared.
-Flatten the logic with an `else if` chain, compound conditions, or sequential
-top-level `if` statements. Sequential top-level conditions execute
-independently, so make their predicates mutually exclusive when only one branch
-should run.
+Sequential top-level `if` statements execute independently. Use them when more
+than one branch may need to run, or when their predicates are intentionally and
+provably mutually exclusive. For new alternative branches, an `else if` chain
+usually expresses first-match priority more clearly. In a bounded repair, do
+not rewrite equivalent, mutually exclusive conditions solely to normalize
+style; require a diagnostic, overlap, gap, priority error, or affected use case.
 
 A direct post-action `if` in a `run @actions.*` body is also supported:
 
@@ -623,17 +668,30 @@ All logic is resolved first; only matching `|` pipe lines are included in the pr
 
 ```agentscript
 instructions: ->
-    | Welcome!
+    | Welcome the user.
     if @variables.is_returning:
-        | Nice to see you again.
+        | Acknowledge that they are returning.
     else:
-        | Let's get started.
-    | How can I help?
+        | Greet them as a new user.
+    | Ask how you can help.
 
 # If is_returning == False, the prompt becomes:
-# "Welcome! Let's get started. How can I help?"
+# "Welcome the user. Greet them as a new user. Ask how you can help."
 ```
 
+Indentation and step numbering inside the emitted pipe text affect only the
+text shown to the model. They do not create nested executable scope. Likewise,
+words such as `Show`, `Ask`, `Call`, `Set`, `STOP`, and `Continue` inside pipe
+text are natural-language instructions, not AgentScript directives.
+
+Action availability is resolved independently from prompt layout. Mentioning an
+action beneath one conditional pipe block does not hide that action when the
+condition is false. Use `available when` when an action must exist only for a
+machine-known branch.
+
+For a review checklist and paired examples, see
+[Common Control-Flow Pitfalls](common-control-flow-pitfalls.md).
+
 ---
 
 ## 9. Flow Control
@@ -708,7 +766,7 @@ reasoning:
         if @variables.order_id != "":
             | Show order details for {!@variables.order_id}.
         else:
-            | I need an order ID to help you.
+            | Ask the user for the order ID needed to continue.
 ```
 
 ---
@@ -929,7 +987,8 @@ run @actions.fetch_order
 
 Utility functions control flow and state. They do not call external systems.
 
-**`@utils.transition to`** — permanent one-way handoff to another subagent:
+**`@utils.transition to`** — non-returning handoff to another subagent (there
+is no automatic return to the source):
 
 ```agentscript
 reasoning:
@@ -939,7 +998,10 @@ reasoning:
             available when @variables.cart_has_items == True
 ```
 
-Transition discards the current subagent's prompt and starts fresh with the target subagent.
+Transition stops the current subagent before another planner call and starts
+the target subagent's lifecycle and prompt resolution. Shared state and
+conversation history persist, and the target may later transition elsewhere,
+including back to the source when the design allows it.
 
 **`@utils.escalate`** — route to a human agent (**service agents only** — requires a `connection messaging:` block, which is only valid for `AgentforceServiceAgent`; do not use in employee agents):
 
@@ -951,7 +1013,9 @@ reasoning:
             available when @variables.needs_human == True
 ```
 
-Escalation ends the current conversation and routes to the escalation system defined in the connection block.
+Escalation ends the current agent turn and hands control to the escalation path
+defined by the connection block. What the downstream human-support session
+does next is outside the AgentScript utility's authoring contract.
 
 **`@utils.setVariables`** — LLM-driven variable capture (slot-filling):
 
@@ -964,7 +1028,19 @@ reasoning:
             with budget = ...
 ```
 
-The LLM extracts values from the conversation and populates the specified variables. **`setVariables` ends the turn after capturing** — instructions do not re-evaluate in the same turn. For "capture X then immediately act on X" patterns, use planner slot-fill directly on the action (`with param = ...`) instead.
+The LLM extracts values from the conversation and populates the specified
+variables through a model-selected tool call. The call updates state but does
+not itself define a turn boundary. Any later reasoning or response follows the
+runtime's normal tool-loop behavior; do not use `setVariables` to force either
+an end or another reasoning iteration.
+
+Do not confuse an instruction to call `setVariables` with the call itself.
+During prompt construction, deterministic `run`, `set`, and `if` statements
+resolve and all `|` text is assembled before the model runs. A `|` instruction
+therefore cannot pause deterministic resolution while the model captures a
+value. For inseparable "capture X, then act on X" behavior, use planner
+slot-fill directly on the real action, deterministic chaining, or one
+purpose-built implementation that owns the complete sequence.
 
 **`@subagent.X`** — delegation to another subagent with return:
 
@@ -978,19 +1054,26 @@ reasoning:
 
 Calling a subagent as a tool runs that subagent's reasoning, then returns control to the calling subagent.
 
-**Post-action directives apply only to `@actions`, not `@utils`**:
+**Utility actions do not expose `@outputs`**:
 
 ```agentscript
-# WRONG — utilities don't support set
+# WRONG — escalation has no output to bind
 escalate: @utils.escalate
-    set @variables.escalated = True
+    set @variables.result = @outputs.status
 
-# CORRECT — only @actions support set
+# CORRECT — backing action output can be captured
 process: @actions.process_order
     set @variables.result = @outputs.status
+
+# SPECIAL CASE — setVariables supports direct state assignments
+mark_ready: @utils.setVariables
+    set @variables.status = "ready"
 ```
 
-Utilities cannot have output, so `set` is invalid.
+Utilities do not provide action outputs, so output-based post-action directives
+are invalid. `@utils.setVariables` is the state-update utility: it supports
+`with` clauses and direct `set @variables...` clauses. It does not support
+follow-up `run` statements or transitions.
 
 ---
 

package/skills/agentforce-generate/references/agent-subagent-map-diagrams.md

@@ -25,8 +25,8 @@ For a multi-subagent agent, it displays:
 - Action calls within subagents (with backing type: Apex, Prompt Template, Flow)
 - Gating conditions (`available when` expressions), when required
 - Variable state changes that have a trusted writer and named consumer
-- Escalation and off-topic handling
-- Conditional instructions based on variable values
+- Escalation, off-topic handling, and conditional instructions when the
+  intended use cases require them
 
 Subagent Map diagrams are the primary visual deliverable in an Agent Spec (design document) and serve both specification and comprehension purposes.
 
@@ -36,10 +36,10 @@ Subagent Map diagrams are the primary visual deliverable in an Agent Spec (desig
 
 ### Graph Orientation
 
-- ALWAYS use `graph TD` (Top-Down orientation)
+- Prefer `graph TD` (top-down) for the provided templates
 - Put the `start_agent` entry point at the top
 - For a router-first design, subagents flow downward from the router
-- Never use other orientations
+- Use another orientation when it makes the actual design materially clearer
 
 ### Node Identification
 
@@ -101,16 +101,21 @@ graph TD
 
 ### Decision/Gating Nodes
 
-Use curly braces `{}` for required deterministic conditions. Common formats:
+Curly braces `{}` create a Mermaid decision diamond. Use a decision node when
+the design actually branches. Label it according to who owns the decision:
 
-- Authorization or confirmation gates: `{Check: customer_verified == true?}`
-- External outcome gates: `{Check: verification_success == true?}`
-- Subagent transition logic: `{user_intent matches?}`
+- Machine-enforced authorization gate: `{customer_verified == true?}`
+- Machine-enforced external outcome gate: `{verification_success == true?}`
+- Model-interpreted transition: `{User wants account help?}`
+
+`Check:` is optional display text, not AgentScript syntax. Do not make a
+semantic model decision look like a machine-enforced predicate, and do not
+invent a deterministic gate merely to satisfy the diagram format.
 
 ```mermaid
 %%{init: {'theme':'neutral'}}%%
 graph TD
-    A[account_changes<br/>Subagent] --> B{Check: customer_verified<br/>== true?}
+    A[account_changes<br/>Subagent] --> B{customer_verified<br/>== true?}
     B -->|Yes| C[Call update_account<br/>backing: Flow]
     B -->|No| D[Call verify_customer<br/>backing: Apex]
 ```
@@ -127,7 +132,7 @@ history and do not need state-change nodes.
 %%{init: {'theme':'neutral'}}%%
 graph TD
     A[Call verify_customer] --> B[Set verified_customer_id<br/>= action output]
-    B --> C{Check: verified_customer_id<br/>!= empty?}
+    B --> C{verified_customer_id<br/>!= empty?}
     C -->|Yes| D[Protected action available]
 ```
 
@@ -160,14 +165,16 @@ graph TD
 
 ### Subagent with Gating Condition
 
-`available when` expressions prevent protected action execution until trusted
-preconditions are met.
+For model-selected actions, `available when` controls whether the action schema
+is exposed in the current reasoning iteration. Use a trusted predicate to keep
+a protected action unavailable until its preconditions are met; independently
+verify authorization again in the backing implementation when required.
 
 ```mermaid
 %%{init: {'theme':'neutral'}}%%
 graph TD
     A[account_changes<br/>Subagent]
-    A --> B{Check: verified_customer_id<br/>!= empty?}
+    A --> B{verified_customer_id<br/>!= empty?}
     B -->|No| C[Call verify_customer<br/>backing: Apex]
     B -->|Yes| D[Protected account action<br/>backing: Flow]
     C --> E[Set verified_customer_id<br/>= action output]
@@ -184,7 +191,7 @@ Do not add a variable solely to create a conditional prompt.
 graph TD
     A[Call verify_customer<br/>backing: Apex]
     A --> B[Set verification_success<br/>= action output]
-    B --> C{Check: verification_success<br/>== true?}
+    B --> C{verification_success<br/>== true?}
     C -->|Yes| D[Offer protected operations]
     C -->|No| E[Explain verification failure]
 ```
@@ -288,15 +295,18 @@ Before finalizing a Subagent Map diagram:
 - [ ] Nodes use sequential capital letter IDs
 - [ ] All subagents labeled with `[subagent_name<br/>Subagent]` format
 - [ ] Action calls include backing type (Apex, Prompt Template, Flow)
-- [ ] Required gating conditions are shown as decision nodes with `{Check: ...?}` format
+- [ ] Machine-enforced gates that materially affect the map are shown as
+      decision nodes and labeled with their actual predicate
+- [ ] Semantic model decisions are labeled in natural language rather than as
+      machine checks
 - [ ] Every shown variable has a trusted writer and named runtime consumer
 - [ ] Variable state changes that affect logic are labeled with `[Set variable = value]`
 - [ ] Escalation uses `[Call @utils.escalate]` format
 - [ ] All transition branches are labeled
-- [ ] Diagram fits in 20-30 nodes
+- [ ] Diagram remains readable; split or summarize it when detail obscures the
+      architecture
 - [ ] Subagent routing from start_agent is clear
-- [ ] Off-topic and escalation paths are visible
-- [ ] Required conditional instruction logic is shown
+- [ ] Required off-topic, escalation, and conditional paths are visible
 
 ---
 
@@ -304,7 +314,6 @@ Before finalizing a Subagent Map diagram:
 
 ### Don't
 
-- Use `graph LR` or other orientations instead of `graph TD`
 - Place `start_agent` anywhere except top (node A)
 - Label actions without backing type information
 - Use ambiguous decision node labels (avoid `{Process?}`)
@@ -315,17 +324,18 @@ Before finalizing a Subagent Map diagram:
 - Create subagent routing without labels on the decision logic
 - Mix subagent nodes with action nodes at same level without clear containment
 - Use custom color styling (breaks in dark mode)
-- Leave off-topic and escalation paths out of diagram
+- Omit off-topic or escalation paths that the intended use cases require
 
 ### Do
 
 - Keep the selected `start_agent` at the top
 - Show all subagents reachable from start_agent
 - Include backing type for every action call
-- Make gating conditions explicit as decision nodes
+- Make material machine-enforced gates explicit as decision nodes
 - Show justified variable updates as separate nodes when they affect logic flow
 - Label all transition branches
-- Include off-topic and escalation subagents
-- Show conditional instructions with decision nodes
+- Include off-topic and escalation subagents when the design calls for them
+- Show material conditional branches without implying that every model
+  judgment is a runtime predicate
 - Use `%%{init: {'theme':'neutral'}}%%` for light/dark mode compatibility
 - Focus diagram on subagent structure, not detailed action logic

package/skills/agentforce-generate/references/agent-validation-and-debugging.md

@@ -31,6 +31,18 @@ Example:
 sf agent validate authoring-bundle --json --api-name Local_Info_Agent
 ```
 
+On an internal test-pod or OrgFarm org, the validation endpoint can return a
+404 whose message explicitly says `SF_TEST_API=false`. In that specific case,
+retry the same command with the test-API switch enabled:
+
+```bash
+SF_TEST_API=true sf agent validate authoring-bundle --json \
+  --api-name Local_Info_Agent --target-org <TEST_ORG_ALIAS>
+```
+
+Do not set `SF_TEST_API=true` for a normal production or sandbox host, and do
+not treat the initial 404 as an Agent Script compile failure.
+
 ### Interpreting Output
 
 When validation succeeds, the JSON output contains `result.success` set to `true`:
@@ -53,9 +65,12 @@ Do not attempt to preview or deploy until validation passes.
 
 ### Validation Checklist (Pre-Validate Mental Model)
 
-Before running the validation command, mentally check these 14 items. This checklist prevents the most common errors and speeds up the feedback loop:
+Before running the validation command, mentally check these 15 items. This checklist prevents the most common errors and speeds up the feedback loop:
 
 - Block ordering is correct: `system` → `access` → `config` → `variables` → `connections` → `knowledge` → `language` → `start_agent` → `subagent` blocks
+- The bundle directory, `.agent` filename, and `.bundle-meta.xml` basename use
+  the same case-sensitive API name; never leave the metadata file named only
+  `bundle-meta.xml`
 - `config` has `developer_name`; service agents also need `access.default_agent_user`
 - `system` block has `messages.welcome`, `messages.error`, and `instructions`
 - `start_agent` block exists with description and at least one transition action
@@ -69,7 +84,8 @@ Before running the validation command, mentally check these 14 items. This check
 - New files use 4-space structural indentation; edited files do not mix styles
 - Names follow naming rules (letters, numbers, underscores only; no spaces; start with letter)
 - No duplicate block names or action names within the same scope
-- Conditional chains use `if / else if / else`, never legacy `elif`; true
+- Exclusive multi-branch logic uses `if / else if / else`; independent top-level
+  conditions are used only when more than one branch may run; `elif` and true
   nested conditionals are avoided
 
 ---
@@ -158,26 +174,36 @@ session_id: linked string
 
 Linked variables are populated from their `source` at runtime. Do not assign a default value.
 
-**7. Post-Action Directives on Utility Actions**
+**7. Output-Based Directives on Utility Actions**
 
 ```agentscript
-# WRONG — utilities don't support post-action directives
+# WRONG — transition has no output to bind
 go_next: @utils.transition to @subagent.next
-    set @variables.navigated = True
+    set @variables.result = @outputs.result
 
-# CORRECT — only @actions support post-action directives
+# CORRECT — backing action output can be captured
 process: @actions.process_order
     set @variables.result = @outputs.result
+
+# SPECIAL CASE — setVariables supports direct state assignments
+mark_navigated: @utils.setVariables
+    set @variables.navigated = True
 ```
 
-Post-action directives (`set`, `run`, `if`, `transition`) only work after `@actions.*` invocations. Utility actions (`@utils.*`) and subagent delegates (`@subagent.*`) do not produce outputs, so post-action directives are not applicable.
+Utility actions and subagent delegates do not produce `@outputs`, so
+output-based directives are not applicable. `@utils.setVariables` is the
+exception for direct state assignment: it accepts `with` and
+`set @variables...`, but not follow-up `run` statements or transitions.
 
 **8. Conditional Syntax**
 
-Use `if / else if / else`; `elif` produces a syntax error. Agentforce lint
-rejects true nested conditionals with `unsupported-nested-if`; the compiler
-also warns about the narrower nested `if/else` condition-slot limitation. For
-examples, post-action behavior, and flattening alternatives, use the canonical
+Use `if / else` for two alternatives and `if / else if / else` for three or
+more alternatives where the first matching branch should win. Spell it
+`else if`; Python-style `elif` is invalid. Use independent top-level `if`
+statements only when more than one branch may run. True nested conditionals are
+unsupported.
+For examples, post-action behavior, and flattening alternatives, use the
+canonical
 [Conditional Control Flow Syntax](agent-script-core-language.md#conditional-control-flow-syntax)
 section rather than maintaining a second syntax guide here.