node output vs workflow output clarification

src/wf_artifacts/drafts/models.py

@@ -308,7 +308,14 @@ class WorkflowDraft(BaseModel):
     state_schema: JsonObject
     output_schema: JsonObject
     outcomes: list[str] = Field(default_factory=lambda: ["ok"], min_length=1)
-    output: list[InputBinding] = Field(default_factory=list)
+    output: list[InputBinding] = Field(
+        default_factory=list,
+        description=(
+            "Top-level workflow output projection. Uses input-binding shape: "
+            "`path` reads from input/state/context and `target` writes to the "
+            "local public output payload. Do not use step output `source` here."
+        ),
+    )
     start: str
     steps: dict[str, DraftStep]
     routes: dict[str, dict[str, str]] = Field(default_factory=dict)

src/wf_core/models/workflow.py

@@ -30,10 +30,11 @@ class Workflow(BaseModel):
     output: list[InputBinding] = Field(
         default_factory=list,
         description=(
-            "Optional final output projection bindings. Sources read from graph "
-            "paths such as state.result, and targets write into the workflow "
-            "output payload. When omitted, legacy same-name top-level state "
-            "projection is used."
+            "Optional final output projection bindings. Uses input-binding shape: "
+            "`path` reads from graph paths such as state.result, and `target` "
+            "writes into the workflow output payload. Use `path`, not `source`; "
+            "`source` belongs to step-level node output bindings. When omitted, "
+            "legacy same-name top-level state projection is used."
         ),
     )
     node_defs: list[NodeDef] = Field(default_factory=list)