feat: add a recipe for the list variables

force-app/main/01_languageEssentials/listVariables/README.md

@@ -0,0 +1,114 @@
+# ListVariables
+
+## Overview
+
+This recipe demonstrates how to use **list variables** to store a collection of values and iterate through them one at a time. The agent runs a daily standup by asking questions from a `list[string]`, tracking progress with an index variable and `len()`.
+
+## Agent Flow
+
+```mermaid
+%%{init: {'theme':'neutral'}}%%
+graph TD
+    A[Start] --> B[start_agent agent_router]
+    B --> C[Transition to run_standup]
+    C --> D{question_index < len?}
+    D -->|Yes| E[Display progress: question N of 3]
+    E --> F[Ask questions at current index]
+    F --> G[User answers]
+    G --> H[LLM calls advance_question]
+    H --> D
+    D -->|No| I[All questions complete]
+    I --> J[Summarize answers]
+```
+
+## Key Concepts
+
+- **List declaration with defaults**: Define a `list[string]` pre-populated with values
+- **Variable-based index access**: Use `@variables.list[@variables.index]` to access items dynamically
+- **`len()` function**: Get the number of items in a list for progress display and loop control
+- **Iteration pattern**: Increment an index variable after each turn to walk through the list
+
+## How It Works
+
+### Declaring a List Variable
+
+```agentscript
+variables:
+   questions: mutable list[string] = ["What did you work on yesterday?", "What are you working on today?", "Do you have any blockers?"]
+      description: "The standup questions to ask the user"
+
+   question_index: mutable number = 0
+      description: "Current position in the questions list"
+```
+
+A list is declared with `list[<type>]` and initialized with values in brackets. Pair it with an index variable to track your position.
+
+### Accessing a List Item by Variable Index
+
+```agentscript
+| Ask this question: {!@variables.questions[@variables.question_index]}
+```
+
+Use `@variables.list[@variables.index]` to access the item at a dynamic position. List indexes start at 0.
+
+### Showing Progress with `len()`
+
+```agentscript
+| Question {!@variables.question_index + 1} of {!len(@variables.questions)}:
+```
+
+`len(@variables.questions)` returns the number of items (3 in this case). Adding 1 to the zero-based index gives human-friendly numbering.
+
+### Iterating Without a For Loop
+
+Agent Script has no `for` loop. Instead, iterate by:
+
+1. Checking `if @variables.question_index < len(@variables.questions)`
+2. Asking the question at the current index
+3. Incrementing the index via a `@utils.setVariables` action
+4. When the index reaches `len()`, the condition flips and the agent summarizes
+
+```agentscript
+actions:
+   advance_question: @utils.setVariables
+      with question_index = @variables.question_index + 1
+      description: "Move to the next question after the user answers."
+```
+
+## Try It Out
+
+### Example Interaction
+
+```text
+Agent: Good morning! Let's run through your daily standup.
+       Question 1 of 3: What did you work on yesterday?
+
+User: I finished the API integration for the billing service.
+
+Agent: Got it. Question 2 of 3: What are you working on today?
+
+User: Writing tests for the billing integration and starting the dashboard UI.
+
+Agent: Nice. Question 3 of 3: Do you have any blockers?
+
+User: Waiting on design mockups for the dashboard.
+
+Agent: Thanks! Here's your standup summary:
+       - Yesterday: Finished billing service API integration
+       - Today: Writing billing tests, starting dashboard UI
+       - Blockers: Waiting on dashboard design mockups
+       Have a productive day!
+```
+
+## What's Next
+
+- **[VariableManagement](../variableManagement/)**: Fundamentals of scalar variables (string, number, boolean)
+- **[TemplateExpressions](../templateExpressions/)**: More on `{!...}` syntax in instructions
+- **[ActionChaining](../../02_actionConfiguration/actionChaining/)**: Populate lists dynamically with `set @variables.list = @outputs.result`
+
+## Notes
+
+- List indexes are **zero-based** — the first item is `[0]`
+- Lists are global — all subagents can access and modify them
+- `len()` can be used in template expressions, conditionals, and `available when` filters
+- Supported list types: `list[string]`, `list[number]`, `list[boolean]`, `list[object]`

force-app/main/01_languageEssentials/listVariables/aiAuthoringBundles/ListVariables/ListVariables.agent

@@ -0,0 +1,49 @@
+# ListVariables - Iterating Through a List
+# This agent demonstrates how to use list variables to work through a sequence of items
+
+config:
+   developer_name: "ListVariables"
+   agent_label: "ListVariables"
+   agent_type: "AgentforceEmployeeAgent"
+   description: "Runs a daily standup by iterating through a list of questions"
+
+variables:
+   questions: mutable list[string] = ["What did you work on yesterday?", "What are you working on today?", "Do you have any blockers?"]
+      description: "The standup questions to ask the user"
+
+   question_index: mutable number = 0
+      description: "Current position in the questions list"
+
+system:
+   messages:
+      welcome: "Good morning! Let's run through your daily standup."
+      error: "Sorry, something went wrong. Let's try that again."
+
+   instructions: "You are a standup facilitator that runs a 3-question daily standup. Ask one question at a time. After the user answers each question, call the advance_question action to move forward. When all questions are done, summarize."
+
+start_agent agent_router:
+   description: "Welcome users and begin the standup"
+
+   reasoning:
+      instructions:|
+         Select the tool that best matches the user's message and conversation history. If it's unclear, make your best guess.
+      actions:
+         go_to_standup: @utils.transition to @subagent.run_standup
+            description: "Run the daily standup questions one at a time."
+
+subagent run_standup:
+   label: "run_standup"
+   description: "Runs the daily standup by asking questions from a list one at a time and tracking progress."
+
+   reasoning:
+      instructions: ->
+         if @variables.question_index < len(@variables.questions):
+            | Question {!@variables.question_index + 1} of {!len(@variables.questions)}:
+            | Ask this question: {!@variables.questions[@variables.question_index]}
+            | After the user answers, call advance_question to move to the next question.
+         else:
+            | All 3 standup questions are complete.
+            | Provide a brief summary of what the user shared and wish them a productive day.
+      actions:
+         advance_question: @utils.setVariables
+            with question_index = @variables.question_index + 1

force-app/main/01_languageEssentials/listVariables/aiAuthoringBundles/ListVariables/ListVariables.bundle-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<AiAuthoringBundle xmlns="http://soap.sforce.com/2006/04/metadata">
+    <bundleType>AGENT</bundleType>
+    <versionTag>v0.1</versionTag>
+</AiAuthoringBundle>