feat: expose composite step inputs

src/wf_cli/commands/draft_add.py

@@ -137,7 +137,10 @@ def add_step_from_capability(
         Path | None,
         typer.Option(
             "--bindings-file",
-            help="Ordered canonical JSON input-binding list.",
+            help=(
+                "Ordered canonical JSON node-input binding list; use this file "
+                "for composite expressions."
+            ),
         ),
     ] = None,
     output_mapping: Annotated[

src/wf_cli/commands/draft_options.py

@@ -13,10 +13,12 @@ from wf_core.models.steps import (
     InputPathBinding,
     InputValueBinding,
     OutputBinding,
+    StepInputBinding,
 )
 from wf_core.paths import GraphSourcePath, LocalPath, PathResolutionError, StatePath
 
-_INPUT_BINDINGS_ADAPTER = TypeAdapter(list[InputBinding])
+_STEP_INPUT_BINDINGS_ADAPTER = TypeAdapter(list[StepInputBinding])
+_WORKFLOW_OUTPUT_BINDINGS_ADAPTER = TypeAdapter(list[InputBinding])
 _OUTPUT_BINDINGS_ADAPTER = TypeAdapter(list[OutputBinding])
 
 
@@ -209,10 +211,10 @@ def _parse_input_value_binding_flags(
     return bindings
 
 
-def parse_step_input_bindings_file(path: Path) -> list[InputBinding]:
-    """Read and validate an ordered canonical input-binding list."""
+def parse_step_input_bindings_file(path: Path) -> list[StepInputBinding]:
+    """Read node-local bindings, including expressions, from canonical JSON."""
     try:
-        return _INPUT_BINDINGS_ADAPTER.validate_python(
+        return _STEP_INPUT_BINDINGS_ADAPTER.validate_python(
             parse_json_file(path, option_name="--bindings-file")
         )
     except ValidationError as exc:
@@ -240,7 +242,7 @@ def parse_workflow_output_value_flags(
 def parse_workflow_output_bindings_file(path: Path) -> list[InputBinding]:
     """Read an ordered canonical workflow-output binding list."""
     try:
-        return _INPUT_BINDINGS_ADAPTER.validate_python(
+        return _WORKFLOW_OUTPUT_BINDINGS_ADAPTER.validate_python(
             parse_json_file(path, option_name="--bindings-file")
         )
     except ValidationError as exc:

src/wf_cli/commands/draft_update.py

@@ -88,7 +88,10 @@ def update_capability_step(
         Path | None,
         typer.Option(
             "--bindings-file",
-            help="Ordered canonical JSON input-binding list.",
+            help=(
+                "Ordered canonical JSON node-input binding list; use this file "
+                "for composite expressions."
+            ),
         ),
     ] = None,
     clear_input: Annotated[

src/wf_cli/commands/drafts.py

@@ -468,7 +468,10 @@ def set_step_input(
         Path | None,
         typer.Option(
             "--bindings-file",
-            help="JSON file containing the complete ordered canonical binding list.",
+            help=(
+                "JSON file containing the complete ordered node-input binding "
+                "list; use this file for composite expressions."
+            ),
         ),
     ] = None,
     clear: Annotated[
@@ -490,7 +493,9 @@ def set_step_input(
     """Replace one step's canonical inputs, or use compatibility map merge.
 
     By default, repeated --map and --value flags replace the complete ordered
-    binding list. --bindings-file replaces from canonical JSON, while --clear
+    binding list. --bindings-file replaces from canonical JSON and is the only
+    way to submit composite expressions; inline --map/--value flags remain
+    simple-only. --clear
     sends an empty list. Use --merge only with map-only compatibility edits;
     it rejects existing bindings that cannot round-trip safely. Canonical
     fan-out or reordered path/literal bindings require complete canonical

src/wf_cli/explain/entries.py

@@ -137,6 +137,7 @@ EXPLAIN_CARDS: tuple[ExplainCard, ...] = (
             "Run `wf schema InputPathBinding` to confirm binding shape.",
             "Inspect the draft input and state schemas.",
             "Use `wf draft set-input --merge` to repair step input bindings.",
+            "Use `wf draft set-input --bindings-file bindings.json` for composite input expressions; inline --map/--value flags remain simple-only.",
             "Patch the draft input_schema/state_schema when the workflow genuinely needs a new path.",
             "Run `wf draft validate <workspace_id>` after the edit.",
         ],