@salesforce/afv-skills 1.32.0 → 1.34.0

package/skills/agentforce-generate/references/agent-metadata-and-lifecycle.md

@@ -18,7 +18,7 @@ Agent Script agents are defined across two independent metadata domains. Underst
 
 ### Two-Domain Entity Graph
 
-```
+```text
 AUTHORING DOMAIN (developer-owned, exists before any publish)
   AiAuthoringBundle
     ├── .agent (Agent Script source — editable text file)
@@ -129,7 +129,7 @@ sf agent generate authoring-bundle --json --no-spec --name "<Label>" --api-name
 
 The command creates two files in a directory named after your `--api-name`:
 
-```
+```text
 aiAuthoringBundles/
   └── Local_Info_Agent/
         ├── Local_Info_Agent.agent (editable source)
@@ -214,9 +214,9 @@ Deploy/retrieve are one-way overwrites with no sync warnings. This is by design
 When deploying backing code (Apex, Flows, Prompt Templates), NEVER include agent metadata (`.agent` files or `AiAuthoringBundle` metadata) unless you explicitly intend to update the agent.
 
 Accidental deployment of an outdated authoring bundle will overwrite in-progress work in the org.
-### `default_agent_user` Configuration: Immutable and Restricted
+### `access.default_agent_user`: Immutable and Restricted
 
-The `default_agent_user` field in your Agent Script `config` block must reference a Salesforce user with the "Einstein Agent" license type. Standard Salesforce-licensed users, even System Administrators, will fail at publish time with a misleading error message: "Internal Error, try again later."
+The `default_agent_user` field in the Agent Script `access` block must reference a Salesforce user with the "Einstein Agent" license type. Standard Salesforce-licensed users, even System Administrators, will fail at publish time with a misleading error message: "Internal Error, try again later."
 
 This error message does NOT indicate a license issue — it masks the true problem.
 
@@ -229,14 +229,14 @@ sf data query --json -q "SELECT Username FROM User WHERE Profile.UserLicense.Nam
 `default_agent_user` can be changed after publish, but only while no published version is activated. Deactivate the agent before changing `default_agent_user`, then republish and reactivate.
 ### Two Validation Layers: Compile vs. API Validation
 
-The CLI `sf agent validate authoring-bundle` checks syntax and Agent Script compilation only. It does NOT validate `default_agent_user` or backing logic references.
+The CLI `sf agent validate authoring-bundle` checks syntax and Agent Script compilation only. It does NOT validate `default_agent_user` or action implementation references.
 
-API validation runs during `sf agent publish` and in Agentforce Studio. This is where `default_agent_user` license requirements are checked and backing logic references are fully validated.
+API validation runs during `sf agent publish` and in Agentforce Studio. This is where `default_agent_user` license requirements are checked and action implementation references are fully validated.
 
-The result: A developer can validate successfully and still fail at publish due to invalid `default_agent_user` or missing backing logic.
-### Deploy Validates Backing Logic via Invocable Action Registry Lookup
+The result: A developer can validate successfully and still fail at publish due to invalid `default_agent_user` or missing action implementations.
+### Deploy Validates Actions via Invocable Action Registry Lookup
 
-When you deploy an `AiAuthoringBundle`, the deployment process validates that every backing logic reference (Apex class, Flow, Prompt Template) resolves to a registered Invocable Action in the org. The referenced class or flow or prompt must exist.
+When you deploy an `AiAuthoringBundle`, the deployment process validates that every action target reference (Apex class, Flow, Prompt Template) resolves to a registered Invocable Action in the org. The referenced class, flow, or prompt must exist.
 
 For Apex classes, the class must have an `@InvocableMethod`-annotated method.
 
@@ -249,7 +249,7 @@ A minimal stub class with `@InvocableMethod` unblocks pro-code/low-code collabor
 
 When deploying a local authoring bundle (`Local_Info_Agent.agent`), the server uses a version-suffixed filename (`Local_Info_Agent_4.agent`), triggering a CLI warning:
 
-```
+```text
 "AiAuthoringBundle, Local_Info_Agent_4.agent, returned from org, but not found in the local project"
 ```
 
@@ -305,7 +305,7 @@ When you publish, the org creates:
 
 Example directory structure after publishing:
 
-```
+```text
 bots/
   └── Local_Info_Agent/
       ├── Local_Info_Agent.bot-meta.xml
@@ -357,11 +357,11 @@ When `sf agent publish authoring-bundle` fails, run these checks in order. Stop
 
 #### 1. Validate `default_agent_user`
 
-Read `agent_type` and `default_agent_user` from the `.agent` config block, then validate based on agent type:
+Read `agent_type` from `config` and `default_agent_user` from `access`, then validate based on agent type:
 
-**If `agent_type` is `AgentforceEmployeeAgent`:** `default_agent_user` must NOT be present. If it is set, remove the entire line.
+**If `agent_type` is `AgentforceEmployeeAgent`:** `default_agent_user` normally must NOT be present. If it is set without a capability-specific requirement, remove the `access` block.
 
-**If `agent_type` is `AgentforceServiceAgent`:** `default_agent_user` must be present. Query the org for the specified username:
+**If `agent_type` is `AgentforceServiceAgent`:** `access.default_agent_user` must be present. Query the org for the specified username:
 
 ```bash
 sf data query --json -q "SELECT Username, IsActive, Profile.UserLicense.Name FROM User WHERE Username = '<default_agent_user_value>'"
@@ -371,9 +371,9 @@ sf data query --json -q "SELECT Username, IsActive, Profile.UserLicense.Name FRO
 - `IsActive` is false → reactivate the user or set a different username.
 - `Profile.UserLicense.Name` is not `"Einstein Agent"` → wrong license. Set a user with the Einstein Agent license.
 
-#### 2. Verify all backing logic is deployed
+#### 2. Verify all action implementations are deployed
 
-Every `target` in the `.agent` file must resolve to a registered backing logic component in the org. Redeploy all backing logic:
+Every `target` in the `.agent` file must resolve to a registered implementation component in the org. Redeploy all action implementations:
 
 ```bash
 sf project deploy start --json --metadata ApexClass Flow PromptTemplate

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

@@ -46,7 +46,7 @@ subagent check_order:
 
 If `@variables.order_id` is `"1001"` and the `fetch_order` action returns `status = "shipped"`, the runtime resolves to this prompt:
 
-```
+```text
 Your order status is shipped.
 You can modify it using the update_order action.
 ```
@@ -59,7 +59,7 @@ This split is critical: **deterministic logic controls WHAT the agent knows (via
 
 ## 2. File Structure and Block Ordering
 
-An Agent Script file (`.agent` extension) contains eight top-level blocks in this mandatory order:
+An Agent Script file (`.agent` extension) contains eight top-level blocks. The recommended order when generating new agents is:
 
 ```agentscript
 system:
@@ -80,6 +80,9 @@ knowledge:
 language:
     ...
 
+modality voice:
+    ...
+
 start_agent agent_router:
     ...
 
@@ -89,7 +92,9 @@ subagent my_subagent:
 
 **Required blocks:** `system`, `config`, `start_agent`, and at least one `subagent`.
 
-**Optional blocks:** `variables`, `connections`, `knowledge`, `language`. Omit them if not needed.
+**Optional blocks:** `variables`, `connections`, `knowledge`, `language`, `modality voice`. Omit them if not needed.
+
+**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.
 
 **Within `start_agent` and `subagent` blocks**, the internal ordering is:
 
@@ -115,9 +120,18 @@ subagent my_subagent:
 
 Example: `check_order_status` is valid. `check_order__status` is invalid (consecutive underscores).
 
-**Indentation:** Use 4 spaces per indent level. NEVER use tabs. Mixing spaces and tabs breaks the parser. All lines at the same nesting level must use the same indentation.
+**Indentation:** Generate new files with 4 spaces per structural level. Four spaces
+is the formatter default and repository convention, not a grammar minimum: the
+language accepts any deeper space indentation relative to the parent. Spaces are
+the specification's standard; tabs are not portable because their behavior is
+implementation-defined. Never mix structural tabs and spaces in one file. When
+making a surgical edit to a consistently tab-indented legacy file, either preserve
+that style and validate against the target runtime or normalize all structural
+indentation as a separate change. Never partially normalize a file or blanket-
+replace tabs inside template content. Lines at the same nesting level must use the
+same indentation width.
 
-Each nesting level adds 4 spaces. The hierarchy follows the block structure — subagent → reasoning → instructions → logic/prompt:
+Each nesting level adds one indent. The hierarchy follows the block structure — subagent → reasoning → instructions → logic/prompt:
 
 ```agentscript
 subagent process_order:
@@ -224,23 +238,30 @@ The `instructions` field is required and contains text directives sent to the LL
 
 Both `welcome` and `error` messages are required.
 
-**Config block** contains agent metadata:
+**Access and config blocks** contain runtime identity and agent metadata:
 
 ```agentscript
+access:
+    default_agent_user: "agent@example.com"
+
 config:
     developer_name: "Customer_Service_Agent"
     agent_label: "Customer Service"
     description: "Handles customer inquiries"
     agent_type: "AgentforceServiceAgent"
-    default_agent_user: "agent@example.com"
 ```
 
+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.
+
 **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.
 - `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:
-    - `default_agent_user`
+    - `access.default_agent_user`
     - MessagingSession linked variables (`EndUserId`, `RoutableId`, `ContactId`, `EndUserLanguage`)
     - Escalation subagent with `@utils.escalate`
     - `connection messaging:` block
@@ -249,9 +270,10 @@ config:
 
   ```agentscript
   # WRONG — employee agent with service-agent constructs
+  access:
+      default_agent_user: "agent@org.ext"    # PROHIBITED — causes "Internal Error"
   config:
       agent_type: "AgentforceEmployeeAgent"
-      default_agent_user: "agent@org.ext"    # PROHIBITED — causes "Internal Error"
   variables:
       EndUserId: linked string               # SERVICE ONLY — no messaging session
           source: @MessagingSession.MessagingEndUserId
@@ -261,11 +283,11 @@ config:
   # RIGHT — clean employee agent config
   config:
       agent_type: "AgentforceEmployeeAgent"
-      # No default_agent_user, no MessagingSession vars, no connection block
+      # No access block, MessagingSession vars, or connection block
   ```
 
 **Conditionally required fields:**
-- `default_agent_user` — **required for `AgentforceServiceAgent`, prohibited for `AgentforceEmployeeAgent`**. This is the Salesforce username of the Einstein Agent User that runs agent actions on behalf of the customer. The user must exist in the target org, be active, and have the Einstein Agent license assigned.
+- `access.default_agent_user` — **required for `AgentforceServiceAgent`, normally omitted for `AgentforceEmployeeAgent`**. This is the Salesforce username of the Einstein Agent User that runs agent actions on behalf of the customer. The user must exist in the target org, be active, and have the Einstein Agent license assigned.
 
   **⚠️ CRITICAL: Setting `default_agent_user` on an `AgentforceEmployeeAgent` causes publish and preview to fail with an unhelpful "unknown error" or "Internal Error, try again later" message.** The error gives no indication that `default_agent_user` is the cause. If you encounter this error on an employee agent, check whether `default_agent_user` is set and remove it.
 
@@ -391,7 +413,11 @@ subagent order_lookup:
 
 **Description is required** — the LLM uses this to understand when the subagent is relevant.
 
-**Subagent-level system override** (optional) — override global system instructions for this subagent only:
+**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,
+repeat every durable identity, safety, and scope invariant the subagent must
+retain:
 
 ```agentscript
 subagent product_specialist:
@@ -438,6 +464,19 @@ 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,
+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
+two surfaces must agree. In particular, do not combine an unconditional global
+instruction to answer or help with instructions that require routing,
+verification, refusal, or escalation without answering. Do not rely on
+structured active-subagent identity or direct variable-store access unless the
+runtime explicitly provides it; state the concrete operating task. See
+[Instruction Resolution](instruction-resolution.md#scope-response-duties-by-branch).
+
 **Arrow syntax (`->`) for logic blocks**:
 
 ```agentscript
@@ -499,42 +538,43 @@ instructions: ->
     | This starts a new logical line.
 ```
 
-**If/Else (no "else if", no nested if)**:
+### Conditional Control Flow Syntax
 
-```agentscript
-# ✅ CORRECT — simple if/else
-if @variables.status == "pending":
-    run @actions.notify_pending
-else:
-    run @actions.notify_complete
+Use `if / else if / else` for one mutually exclusive chain:
 
-# ❌ WRONG — else if not supported
+```agentscript
+# Supported multi-branch chain
 if @variables.count < 5:
     run @actions.small
 else if @variables.count < 10:
     run @actions.medium
-
-# ❌ WRONG — nested if inside else is also invalid
-if @variables.status == "pending":
-    run @actions.queue_pending
 else:
-    if @variables.status == "closed":
-        run @actions.archive
-```
+    run @actions.large
 
-For multi-branch logic, use compound conditions (`if A and B:`) or flatten to sequential `if` statements.
+# Invalid legacy spelling
+if @variables.count < 5:
+    run @actions.small
+elif @variables.count < 10:
+    run @actions.medium
+```
 
-**Inline action invocation (`run @actions.X`)**:
+`else if` is supported and may repeat before the optional final `else`. `elif`
+is not an AgentScript keyword and produces a syntax error.
 
-```agentscript
-run @actions.check_inventory
-    with product_id = @variables.selected_product
-    set @variables.stock_level = @outputs.available_quantity
-```
+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.
 
-The `run` command executes the action deterministically — the runtime runs it before the LLM reasons. Use `with` to pass inputs (bound to variables or literal values). Use `set` to capture outputs into variables.
+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.
 
-**Post-action directives** (only for `@actions`, not `@utils`):
+A direct post-action `if` in a `run @actions.*` body is also supported:
 
 ```agentscript
 run @actions.process_order
@@ -546,7 +586,19 @@ run @actions.process_order
         transition to @subagent.error_handling
 ```
 
-After an action completes, you can check outputs and transition.
+**Inline action invocation (`run @actions.X`)**:
+
+```agentscript
+run @actions.check_inventory
+    with product_id = @variables.selected_product
+    set @variables.stock_level = @outputs.available_quantity
+```
+
+The `run` command executes the action deterministically — the runtime runs it before the LLM reasons. Use `with` to pass inputs (bound to variables or literal values). Use `set` to capture outputs into variables.
+
+**Post-action directives** work only for `@actions`, not `@utils`. After an
+action completes, you can check outputs and transition as shown in the
+conditional syntax section above.
 
 **Scope lifecycle — `@inputs` and `@outputs` are ephemeral:**
 - `@inputs`: only in `with` directives during invocation. NOT in `set`/`if` after execution.
@@ -716,7 +768,7 @@ actions:
 - `is_displayable` (boolean) — controls whether output is shown to the customer
 - `complex_data_type_name` — required for complex data types like SObject references (e.g., `"lightning__recordInfoType"`), Apex inner classes, and custom Lightning types. Not needed for simple types like `date`, `integer`, or `datetime` — use the simple type directly.
 
-**Parameter names must exactly match the backing logic interface — including case.** Read the target class before writing the action definition.
+**Parameter names must exactly match the action implementation interface — including case.** Read the target class before writing the action definition.
 
 Given this Apex class:
 
@@ -912,7 +964,7 @@ reasoning:
             with budget = ...
 ```
 
-The LLM extracts values from the conversation and populates the specified variables.
+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.
 
 **`@subagent.X`** — delegation to another subagent with return:
 

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

@@ -14,14 +14,17 @@
 
 ## Purpose and Context
 
-A Subagent Map diagram is a Mermaid flowchart that visualizes an agent's subagent graph structure. It shows the architecture of an agent before implementation, displaying:
+A Subagent Map diagram is a Mermaid flowchart that visualizes an agent's
+subagent graph structure. Use the smallest graph that represents the design.
+For a multi-subagent agent, it displays:
 
-- The start_agent agent_router entry point
+- The `start_agent agent_router` entry point when multiple genuine domains need
+  intent classification
 - All subagents in the agent
 - Subagent transitions and routing logic
 - Action calls within subagents (with backing type: Apex, Prompt Template, Flow)
-- Gating conditions (available_when expressions)
-- Variable state changes
+- 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
 
@@ -34,8 +37,8 @@ Subagent Map diagrams are the primary visual deliverable in an Agent Spec (desig
 ### Graph Orientation
 
 - ALWAYS use `graph TD` (Top-Down orientation)
-- Start with start_agent agent_router at the top
-- Subagents flow downward from the router
+- Put the `start_agent` entry point at the top
+- For a router-first design, subagents flow downward from the router
 - Never use other orientations
 
 ### Node Identification
@@ -98,30 +101,34 @@ graph TD
 
 ### Decision/Gating Nodes
 
-Use curly braces `{}` for conditions. Common formats:
+Use curly braces `{}` for required deterministic conditions. Common formats:
 
-- Variable availability gates: `{Check: variable_name != empty?}`
-- Conditional instructions: `{variable_name == value?}`
+- Authorization or confirmation gates: `{Check: customer_verified == true?}`
+- External outcome gates: `{Check: verification_success == true?}`
 - Subagent transition logic: `{user_intent matches?}`
 
 ```mermaid
 %%{init: {'theme':'neutral'}}%%
 graph TD
-    A[subagent<br/>Subagent] --> B{Check: guest_interests<br/>!= empty?}
-    B -->|Yes| C[Call collect_events<br/>backing: Prompt Template]
-    B -->|No| D[Ask for clarification]
+    A[account_changes<br/>Subagent] --> B{Check: customer_verified<br/>== true?}
+    B -->|Yes| C[Call update_account<br/>backing: Flow]
+    B -->|No| D[Call verify_customer<br/>backing: Apex]
 ```
 
 ### Variable State Change Nodes
 
-Format: `[Set variable_name = value]`
+Format: `[Set verified_customer_id<br/>= action output]`
 
-Shows state modifications that affect downstream behavior.
+Show a state modification only when a later runtime gate, transition, or action
+binding consumes it. Ordinary conversational facts belong in conversation
+history and do not need state-change nodes.
 
 ```mermaid
 %%{init: {'theme':'neutral'}}%%
 graph TD
-    A[Call action] --> B[Set reservation_required<br/>= true]
+    A[Call verify_customer] --> B[Set verified_customer_id<br/>= action output]
+    B --> C{Check: verified_customer_id<br/>!= empty?}
+    C -->|Yes| D[Protected action available]
 ```
 
 ### Utility Call Nodes
@@ -153,31 +160,33 @@ graph TD
 
 ### Subagent with Gating Condition
 
-Available_when expressions prevent action execution until conditions are met.
+`available when` expressions prevent protected action execution until trusted
+preconditions are met.
 
 ```mermaid
 %%{init: {'theme':'neutral'}}%%
 graph TD
-    A[subagent_with_gate<br/>Subagent]
-    A --> B{Check: required_var<br/>!= empty?}
-    B -->|No| C[Instruction: collect info first]
-    B -->|Yes| D[Call action<br/>backing: Prompt Template]
-    C --> E[Wait for input]
+    A[account_changes<br/>Subagent]
+    A --> B{Check: 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]
     E --> A
 ```
 
 ### Subagent with Conditional Instructions
 
-Variable values control which instructions apply to a subagent.
+Trusted action outputs or named invariants may control which instructions apply.
+Do not add a variable solely to create a conditional prompt.
 
 ```mermaid
 %%{init: {'theme':'neutral'}}%%
 graph TD
-    A[Call process_request<br/>backing: Flow]
-    A --> B[Set status_flag = complete]
-    B --> C{Check: status_flag<br/>== complete?}
-    C -->|Yes| D[Apply conditional<br/>instructions]
-    D --> E[Continue]
+    A[Call verify_customer<br/>backing: Apex]
+    A --> B[Set verification_success<br/>= action output]
+    B --> C{Check: verification_success<br/>== true?}
+    C -->|Yes| D[Offer protected operations]
+    C -->|No| E[Explain verification failure]
 ```
 
 ### Subagent Transitions
@@ -212,7 +221,9 @@ graph TD
 
 ## Complete Example: Local_Info_Agent
 
-This example demonstrates a complete Subagent Map for a guest information agent with multiple subagents, gating conditions, variable state, and escalation handling.
+This example demonstrates a complete Subagent Map for a guest information
+agent. It needs no mutable state: surviving conversation history carries
+follow-up context, and each action can slot-fill its input from the conversation.
 
 ```mermaid
 %%{init: {'theme':'neutral'}}%%
@@ -229,20 +240,11 @@ graph TD
     B --> B1[Call check_weather<br/>backing: Apex]
     B1 --> B2[Continue]
 
-    C --> C1{Check: guest_interests<br/>!= empty?}
-    C1 -->|No| C2[Instruction: collect guest interests]
-    C1 -->|Yes| C3[Call check_events<br/>backing: Prompt Template]
-    C2 --> C4[Pause for input]
-    C4 --> C
-    C3 --> C5[Continue]
+    C --> C1[Call check_events<br/>backing: Prompt Template]
+    C1 --> C2[Continue]
 
     D --> D1[Call get_resort_hours<br/>backing: Flow]
-    D1 --> D2[Set reservation_required<br/>= true]
-    D2 --> D3{Check: reservation_required<br/>== true?}
-    D3 -->|Yes| D4[Apply booking instructions]
-    D3 -->|No| D5[Apply standard instructions]
-    D4 --> D6[Continue]
-    D5 --> D6
+    D1 --> D2[Continue]
 
     E --> E1[Instruction: ask for clarification]
     E1 --> E2[Await user input]
@@ -259,9 +261,11 @@ graph TD
 
 **local_weather**: Provides weather information via Apex-backed action. No preconditions.
 
-**local_events**: Requires guest_interests variable to be populated (gating: `available_when guest_interests != ""`). Calls Prompt Template-backed action only when gate is satisfied.
+**local_events**: Uses the Prompt Template-backed action when the user asks for
+events. Its conversational input is slot-filled from the current turn and
+surviving history.
 
-**resort_hours**: Calls Flow-backed action that sets reservation_required variable. Conditional instructions applied based on variable state: booking-specific guidance when true, standard guidance when false.
+**resort_hours**: Calls a Flow-backed action and presents its returned hours.
 
 **ambiguous_question**: No actions. Requests clarification and routes back to start_agent.
 
@@ -279,18 +283,20 @@ Before finalizing a Subagent Map diagram:
 
 - [ ] Uses `graph TD` syntax
 - [ ] Starts with `%%{init: {'theme':'neutral'}}%%`
-- [ ] start_agent agent_router is node A at top
+- [ ] `start_agent` is node A at top; use `agent_router` only for a
+      router-first multi-domain design
 - [ ] Nodes use sequential capital letter IDs
 - [ ] All subagents labeled with `[subagent_name<br/>Subagent]` format
 - [ ] Action calls include backing type (Apex, Prompt Template, Flow)
-- [ ] Gating conditions shown as decision nodes with `{Check: ...?}` format
-- [ ] Variable state changes explicitly labeled with `[Set variable = value]`
+- [ ] Required gating conditions are shown as decision nodes with `{Check: ...?}` format
+- [ ] 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
 - [ ] Subagent routing from start_agent is clear
 - [ ] Off-topic and escalation paths are visible
-- [ ] Conditional instruction logic is shown
+- [ ] Required conditional instruction logic is shown
 
 ---
 
@@ -299,11 +305,13 @@ 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)
+- Place `start_agent` anywhere except top (node A)
 - Label actions without backing type information
 - Use ambiguous decision node labels (avoid `{Process?}`)
 - Hide gating conditions in node descriptions instead of showing as decisions
 - Omit variable state changes that affect downstream behavior
+- Add variables for facts already available in surviving conversation history
+- Show a state node without its trusted writer and named consumer
 - 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)
@@ -311,11 +319,11 @@ Before finalizing a Subagent Map diagram:
 
 ### Do
 
-- Keep start_agent agent_router at the top
+- 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
-- Show variable updates as separate nodes when they affect logic flow
+- 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