docs: clarify draft bind input behavior

docs/current_roadmap.md

@@ -100,6 +100,9 @@ clear operator feedback before adding more architecture.
   project missing top-level output schema fields from declared `input.*` and
   `state.*` sources, and challenge prompt templates now always include
   `ux_issues_found: []` so debug-profile reports do not fail by omission.
+- Completed: `wf draft bind` now reuses existing workflow input/state schema
+  fields when binding to step-local inputs, avoiding redundant-schema failures
+  found by debug challenge runs.
 - Keep status read-only; do not mutate registry, auth, config, or stores.
 
 ## Priority 2: Durable Run/Resume Hardening

docs/wf_cli.md

@@ -361,6 +361,10 @@ wf draft bind concat_ws --revision 9 --step call --from local.result --to output
 wf draft validate concat_ws
 ```
 
+If the workflow schema field already exists, `bind` reuses it and only updates
+the step binding. Use `set-input --merge` for pure input-map edits when no
+schema projection is needed.
+
 When validation gives a `repair_hint` with an exact focused `wf draft bind`
 command, run it before falling back to JSON Patch.
 

skills/wf-cli/SKILL.md

@@ -57,8 +57,9 @@ wf draft save <workspace_id> --artifact <artifact_id> --version <n> --title <tit
 Draft creation auto-binds required capability inputs only. Optional inputs are
 reported in wrapper-hint notes; bind them explicitly only when the workflow
 should expose them. Use `wf draft bind --from input.x --to local.x` for an
-existing step, or `wf draft add-step --input input.x=x` while adding a step;
+existing step when schema projection may be needed; it is safe if the schema
-both project the workflow input schema for top-level fields.
+field already exists. Use `wf draft set-input --merge --map input.x=x` for a
+pure input-map edit when the workflow schema is already declared.
 
 `wf draft set-workflow-output` projects missing public output schema fields for
 single-field `input.*` and `state.*` sources. Prefer it for final workflow

skills/wf-workflow/references/draft-workspaces.md

@@ -129,6 +129,11 @@ the whole map for that step or output scope. Use repeated `--map` flags in one
 command for a complete replacement. Use `--merge` only when adding/updating
 entries over multiple revisions.
 
+`bind input.x -> local.x` is schema-aware and idempotent when `input.x` is
+already declared. Use it for repair hints or schema projection. Use
+`set-input --merge --map input.x=x` when you only need to update a step input
+map.
+
 - `bind_draft`
 
   Declares a workflow input/state/output schema field from a capability local

src/wf_cli/commands/drafts.py

@@ -404,11 +404,13 @@ def bind_draft(
         typer.Option("--to", help="Target path, for example local.x or state.y."),
     ],
 ) -> None:
-    """Bind a capability step path and project the matching schema.
+    """Bind a capability step path and project missing schema when needed.
 
     Direction matters. Use input/state -> local for step inputs and local ->
-    state/output for step outputs. Run `wf draft validate <workspace_id>` after
+    state/output for step outputs. If the workflow schema field already exists,
-    this command.
+    the command reuses it and updates the step binding. For pure input-map edits
+    where schema is already known, `wf draft set-input --merge` is also valid.
+    Run `wf draft validate <workspace_id>` after this command.
     """
     context = load_cli_context(ctx)
     emit_json(

tests/wf_cli/test_app.py

@@ -167,10 +167,12 @@ def test_wf_draft_bind_help_explains_direction() -> None:
     result = runner.invoke(app, ["draft", "bind", "--help"])
 
     assert result.exit_code == 0
-    output = " ".join(result.output.split())
+    help_text = " ".join(result.output.split())
-    assert "--from" in output
+    assert "--from" in help_text
-    assert "--to" in output
+    assert "--to" in help_text
-    assert "validate" in output
+    assert "validate" in help_text
+    assert "project missing schema" in help_text
+    assert "set-input --merge" in help_text
 
 
 def test_wf_draft_add_step_help_explains_explicit_wiring() -> None: