docs: clarify semantic draft CLI behavior

docs/wf_cli.md

@@ -338,6 +338,9 @@ Use `set-route` separately for outcome routing.
 
 Use `wf draft add-step-from-capability` when adding a new capability-backed step
 to an existing draft. The command is explicit: it does not guess missing maps.
+When the capability declares multiple outcomes, provide exactly one
+`--route OUTCOME=TARGET` for each declared outcome. Missing or unknown outcomes
+are rejected before the draft is mutated.
 
 ```bash
 wf draft add-step-from-capability report_ws \
@@ -371,15 +374,17 @@ wf draft handle concat_ws --revision 7 --to fail --branch lookup:error --branch
 
 ### Compile A Draft Workspace
 
-Use `wf draft compile` to return the compiled raw plan plus required
+Use `wf draft compile` to print the compiled raw plan without mutating or saving
-capabilities without mutating or saving the draft:
+the draft:
 
 ```bash
 wf draft compile concat_ws
 ```
 
-On success, prints the compiled plan to stdout. On invalid draft status, prints
+On success, stdout is the raw plan JSON itself, not a `compiled_plan` envelope.
-the structured diagnostic envelope to stderr and exits nonzero.
+The API/RPC/MCP operation also returns required capability metadata. On invalid
+draft status, the CLI prints the structured diagnostic envelope to stderr and
+exits nonzero.
 
 Validate:
 

skills/wf-cli/SKILL.md

@@ -91,6 +91,10 @@ Patch for non-capability/control draft steps.
 To add a capability step, prefer `wf draft add-step-from-capability` over raw
 JSON Patch when the route, input bindings, and output-to-state bindings are
 known. It is explicit and does not guess missing maps.
+If a capability has multiple outcomes, pass one `--route OUTCOME=TARGET` for
+each declared outcome; extra outcome names are rejected.
+`wf draft compile` prints the raw plan JSON directly on success. Do not expect a
+top-level `compiled_plan` key from the CLI output.
 
 ## Rules
 

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

@@ -126,9 +126,10 @@ wf draft validate <workspace_id>
   output-to-state schema/binding wiring in one revision. It can set the incoming
   edge, outgoing edges, input map, and output-to-state schema/binding. Use
   `--route OUTCOME=TARGET` for each outcome; when omitted and the capability
-  declares a single outcome, that outcome routes to `__end__`. It still
+  declares a single outcome, that outcome routes to `__end__`. Multi-outcome
-  requires explicit choices; if you do not know a map, inspect the capability or
+  capabilities require exact route coverage; missing or unknown outcomes are
-  run validation rather than guessing.
+  rejected before mutation. It still requires explicit choices; if you do not
+  know a map, inspect the capability or run validation rather than guessing.
 
 ```bash
 wf draft add-step-from-capability <workspace_id> --revision <n> --step <step_id> --capability <qualified_name> --from-step <prev> --from-outcome ok --route ok=__end__ --route error=fail --input input.text=text --bind-output result=state.result
@@ -149,9 +150,10 @@ wf draft validate <workspace_id>
 
 - `compile_draft_workspace`
 
-  Returns the compiled raw plan plus required capabilities without mutating
+  API/RPC/MCP returns the compiled raw plan plus required capabilities without
-  or saving the draft workspace. On invalid draft status, returns structured
+  mutating or saving the draft workspace. The CLI prints only the raw plan JSON
-  diagnostics without a `compiled_plan`.
+  on success. On invalid draft status, it returns structured diagnostics without
+  a `compiled_plan`.
 
 Validation repair hints are product guidance. If a diagnostic suggests
 `bind-output-to-state`, use it before hand-editing `state_schema` or step output