docs

src/wf_artifacts/drafts/adapter.py

@@ -19,7 +19,12 @@ from .models import (
 
 
 def build_workflow_from_draft(draft: WorkflowDraft) -> Workflow:
-    """Adapt one typed draft through `WorkflowBuilder` into a core workflow."""
+    """Adapt one typed draft through `WorkflowBuilder` into a core workflow.
+
+    Draft step `output` bindings become node-output-to-state writes. Final
+    workflow output projection stays in core runtime and uses output schema
+    property names as state keys.
+    """
     builder = WorkflowBuilder(
         name=draft.name,
         input_schema=draft.input_schema,

src/wf_artifacts/drafts/models.py

@@ -28,7 +28,12 @@ STEP_KIND_KEYS = frozenset(
 
 
 class DraftUseStep(BaseModel):
-    """Draft step that calls one externally resolvable workflow capability."""
+    """Draft step that calls one externally resolvable workflow capability.
+
+    `output` writes node-local output fields into workflow state. It does not
+    define final workflow output; core currently projects final output from
+    state keys whose names match `WorkflowDraft.output_schema.properties`.
+    """
 
     model_config = ConfigDict(extra="forbid", populate_by_name=True)
 
@@ -270,7 +275,13 @@ DraftStep = (
 
 
 class WorkflowDraft(BaseModel):
-    """Patch-friendly JSON authoring document for one workflow graph."""
+    """Patch-friendly JSON authoring document for one workflow graph.
+
+    There is intentionally no top-level output map in this draft shape. Final
+    workflow output is projected from state by matching output-schema property
+    names, so terminal steps should write required output fields to same-named
+    state paths.
+    """
 
     name: str
     input_schema: JsonObject