feat: allow expressions in add-to-list statements

Studio Pro stores list-add values as expression strings, but MDL only accepted `add $Item to $List` and the AST kept only a bare item variable. Round-tripping a list-add action whose value is an attribute path or function call could therefore lose the original expression shape.

The grammar now accepts `add expression to $List`, the visitor stores the parsed expression while keeping the simple-variable compatibility field, and the builder writes the expression value back to the `ChangeListAction`. The existing variable-only form remains supported.

Tests cover parser and builder behavior for expression and simple-variable forms. The branch also adds a draft proposal, doctype fixture, quick-reference entry, and skill guidance; `mxcli check` on the fixture plus make build, make lint-go, and make test pass locally.

Author: hjothamendix

.claude/skills/mendix/write-microflows.md

@@ -400,6 +400,18 @@ commit $Product with events refresh;
 
 **Best Practice**: Use `with events` when you want before/after commit event handlers to execute. Use `refresh` when the committed object is displayed in the client and you want the UI to update immediately.
 
+## List Operations
+
+```mdl
+-- Existing variable form
+add $Item to $Items;
+
+-- Expression-valued add, useful when round-tripping Studio Pro list-add values
+add head($SourceItems) to $Items;
+```
+
+Use expression-valued `add` only when the expression returns an object compatible with the target list element type.
+
 ## Database Operations
 
 ### RETRIEVE Statement

docs/01-project/MDL_QUICK_REFERENCE.md

@@ -221,6 +221,7 @@ authentication basic, session
 | Rollback | `rollback $entity [refresh];` | Reverts uncommitted changes |
 | Retrieve (DB) | `retrieve $Var from Module.Entity [where condition];` | Database XPath retrieve |
 | Retrieve (Assoc) | `retrieve $list from $Parent/Module.AssocName;` | Retrieve by association |
+| Add to list | `add expression to $list;` | Also accepts existing `add $item to $list;` form |
 | Call microflow | `$Result = call microflow Module.Name (Param = $value);` | |
 | Call nanoflow | `$Result = call nanoflow Module.Name (Param = $value);` | |
 | Show page | `show page Module.PageName ($Param = $value);` | Also accepts `(Param: $value)` |

docs/11-proposals/PROPOSAL_microflow_add_expression_to_list.md

@@ -0,0 +1,33 @@
+# Proposal: Microflow ADD Expression To List
+
+Status: Draft
+
+## Summary
+
+Allow `add` microflow statements to use any expression as the value being added to a list:
+
+```mdl
+add head($SourceList) to $TargetList;
+```
+
+The existing variable-only form remains valid:
+
+```mdl
+add $Item to $TargetList;
+```
+
+## Motivation
+
+Studio Pro stores the value of a list-add action as an expression string. Existing models can therefore contain a list-add value that is not a bare variable. MDL previously parsed only `add $Item to $List`, so describe/exec round-trips could not preserve expression-valued list additions.
+
+## Semantics
+
+The parser stores the add value as an expression. For compatibility, a bare variable expression also populates the legacy `Item` field in the AST. The builder writes the expression source to the Mendix `ChangeListAction.Value` field and falls back to the legacy item variable only when no expression is present.
+
+## Tests And Examples
+
+`mdl-examples/doctype-tests/add_expression_to_list.test.mdl` demonstrates adding `head($SourceList)` to another list. Go regression tests cover parser behavior and builder output for both expression and simple-variable forms.
+
+## Open Questions
+
+- Should validation infer the list element type and reject expressions that cannot produce an object compatible with the target list?

docs/11-proposals/README.md

@@ -47,6 +47,7 @@ BSON schema Registry ◄──── multi-version Support
 | [Page Styling Support](page-styling-support.md) | Partial | CSS classes, inline styles, dynamic classes, design properties. Phase 1 (Class/Style) done | — |
 | [Page Composition](proposal_page_composition.md) | Proposed | Fragment definitions and ALTER PAGE for partial page editing | Page Syntax V2, Page Styling |
 | [XPath Gaps](xpath-gaps-proposal.md) | Partial | XPath constraint support gap analysis. ~85% complete, association paths and nested predicates remain | — |
+| [Microflow ADD Expression To List](PROPOSAL_microflow_add_expression_to_list.md) | Draft | Preserve expression-valued list-add actions in microflow round-trips | — |
 | [LLM MDL Assistance](PROPOSAL_llm_mdl_assistance.md) | Proposed | Enhanced error messages with examples, reorganized skills by use case | — |
 
 ### Testing & Evaluation

mdl-examples/doctype-tests/add_expression_to_list.test.mdl

@@ -0,0 +1,17 @@
+create module AddListExample;
+
+create persistent entity AddListExample.Item (
+  Name: string
+);
+/
+
+create microflow AddListExample.AddFirstItem (
+  $SourceItems: list of AddListExample.Item
+)
+returns list of AddListExample.Item as $Items
+begin
+  $Items = create list of AddListExample.Item;
+  add head($SourceItems) to $Items;
+  return $Items;
+end;
+/

mdl/ast/ast_microflow.go

@@ -504,9 +504,10 @@ type CreateListStmt struct {
 
 func (s *CreateListStmt) isMicroflowStatement() {}
 
-// AddToListStmt represents: ADD $Item TO $List
+// AddToListStmt represents: ADD expr TO $List
 type AddToListStmt struct {
-	Item        string               // Item variable to add
+	Item        string               // Item variable to add, kept for simple $Var compatibility
+	Value       Expression           // Item expression to add
 	List        string               // Target list variable
 	Annotations *ActivityAnnotations // Optional @position, @caption, @color, @annotation
 }

mdl/executor/cmd_microflows_builder_actions.go

@@ -686,11 +686,15 @@ func (fb *flowBuilder) addCreateListAction(s *ast.CreateListStmt) model.ID {
 
 // addAddToListAction creates an ADD TO list statement.
 func (fb *flowBuilder) addAddToListAction(s *ast.AddToListStmt) model.ID {
+	value := fb.exprToString(s.Value)
+	if value == "" && s.Item != "" {
+		value = "$" + s.Item
+	}
 	action := &microflows.ChangeListAction{
 		BaseElement:    model.BaseElement{ID: model.ID(types.GenerateID())},
 		Type:           microflows.ChangeListTypeAdd,
 		ChangeVariable: s.List,
-		Value:          "$" + s.Item,
+		Value:          value,
 	}
 
 	activity := &microflows.ActionActivity{

mdl/executor/cmd_microflows_builder_add_to_list_test.go

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package executor
+
+import (
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+	"github.com/mendixlabs/mxcli/sdk/microflows"
+)
+
+func TestAddToListBuilderUsesExpressionValue(t *testing.T) {
+	fb := &flowBuilder{}
+
+	fb.addAddToListAction(&ast.AddToListStmt{
+		Value: &ast.AttributePathExpr{
+			Variable: "Order",
+			Path:     []string{"Number"},
+		},
+		List: "Numbers",
+	})
+
+	action := lastChangeListAction(t, fb)
+	if action.Value != "$Order/Number" {
+		t.Fatalf("Value = %q, want $Order/Number", action.Value)
+	}
+}
+
+func TestAddToListBuilderKeepsSimpleVariableFallback(t *testing.T) {
+	fb := &flowBuilder{}
+
+	fb.addAddToListAction(&ast.AddToListStmt{
+		Item: "Order",
+		List: "Orders",
+	})
+
+	action := lastChangeListAction(t, fb)
+	if action.Value != "$Order" {
+		t.Fatalf("Value = %q, want $Order", action.Value)
+	}
+}
+
+func lastChangeListAction(t *testing.T, fb *flowBuilder) *microflows.ChangeListAction {
+	t.Helper()
+
+	if len(fb.objects) == 0 {
+		t.Fatal("Expected builder to create an action activity")
+	}
+	activity, ok := fb.objects[len(fb.objects)-1].(*microflows.ActionActivity)
+	if !ok {
+		t.Fatalf("Last object = %T, want ActionActivity", fb.objects[len(fb.objects)-1])
+	}
+	action, ok := activity.Action.(*microflows.ChangeListAction)
+	if !ok {
+		t.Fatalf("Action = %T, want ChangeListAction", activity.Action)
+	}
+	return action
+}

mdl/grammar/MDLParser.g4

@@ -1867,7 +1867,7 @@ createListStatement
  * ```
  */
 addToListStatement
-    : ADD VARIABLE TO VARIABLE
+    : ADD expression TO VARIABLE
     ;
 
 /**