docs: complete capability step updates

docs/current_roadmap.md

@@ -822,6 +822,12 @@ stable.
   and is available through Python, JSON-RPC, MCP, and local/remote CLI modes.
   Compatibility map merges remain available but inherently lossy. Implementation
   plan: [`atomic step output bindings`](historical/superpowers/plans/2026-07-23-atomic-step-output-bindings.md).
+- Completed: capability-step creation now accepts metadata and ordered
+  path/literal inputs, while focused presence-aware updates can clear selected
+  metadata or atomically replace canonical inputs without changing `use`,
+  routes, or outputs. Python, JSON-RPC, MCP, and local/remote CLI surfaces are
+  aligned. Implementation plan:
+  [`capability step updates`](historical/superpowers/plans/2026-07-26-capability-step-update.md).
 
 Agent evaluation cohort status and policy:
 

docs/historical/superpowers/plans/2026-07-26-capability-step-update.md

@@ -856,7 +856,7 @@ git commit -m "feat: add capability step update cli"
 - Produces: accurate current docs, closed issue state, archived checked plan,
   and final review evidence.
 
-- [ ] **Step 1: Update issue and roadmap state**
+- [x] **Step 1: Update issue and roadmap state**
 
 Mark the focused capability-step update issue complete. State that:
 
@@ -868,7 +868,7 @@ Mark the focused capability-step update issue complete. State that:
 
 Add a completed roadmap entry linked to the historical plan.
 
-- [ ] **Step 2: Update user and agent docs**
+- [x] **Step 2: Update user and agent docs**
 
 Document:
 
@@ -892,7 +892,7 @@ Explain omission versus clearing, complete input replacement, bindings-file
 interleaving, and separate route/output operations. Add JSON-RPC and MCP
 operation names to live inventories.
 
-- [ ] **Step 3: Archive the checked plan**
+- [x] **Step 3: Archive the checked plan**
 
 Mark every checkbox complete, move the plan to the historical path, and update
 all live links:
@@ -901,7 +901,7 @@ all live links:
 rg -n '2026-07-26-capability-step-update' docs skills README.md
 ```
 
-- [ ] **Step 4: Run the full focused matrix**
+- [x] **Step 4: Run the full focused matrix**
 
 Run:
 
@@ -920,7 +920,7 @@ Run:
 
 Expected: PASS with only already-known dependency deprecation warnings.
 
-- [ ] **Step 5: Run static verification**
+- [x] **Step 5: Run static verification**
 
 Run:
 
@@ -933,7 +933,7 @@ git diff --check
 
 Expected: all clean.
 
-- [ ] **Step 6: Run independent two-axis review**
+- [x] **Step 6: Run independent two-axis review**
 
 Review from commit `05afc2e1` through the current worktree against:
 
@@ -959,7 +959,7 @@ reviewer must inspect:
 
 Fix every Critical and Important finding and rerun affected checks.
 
-- [ ] **Step 7: Commit documentation and review fixes**
+- [x] **Step 7: Commit documentation and review fixes**
 
 Commit documentation:
 

docs/wf_cli.md

@@ -461,18 +461,35 @@ unknown route entries and add one route for each missing declared outcome.
 ```bash
 wf draft add capability report_ws \
   --revision 3 \
-  --step render \
-  --capability local.report.render_markdown_report \
+  --step publish \
+  --capability local.report.publish \
+  --description "Publish report" \
+  --retry 2 \
+  --timeout-seconds 30 \
   --from-step extract \
   --from-outcome ok \
   --route ok=__end__ \
-  --route error=tool_error \
-  --input state.title=title \
-  --input state.summary=summary \
-  --bind-output markdown=state.markdown \
-  --bind-output title=state.title
+  --input state.report.title=request.title \
+  --value request.format='"markdown"'
+
+wf draft update capability report_ws \
+  --revision 4 \
+  --step publish \
+  --clear-description \
+  --retry 0 \
+  --clear-timeout
 ```
 
+On update, an omitted field is preserved. A matching `--clear-*` flag removes
+that metadata override; `--retry 0` is a real value, not omission. Supplying
+`--input` and/or `--value` replaces the step's complete ordered canonical input
+list. `--clear-input` replaces it with `[]`. Use `--bindings-file` for exact
+path/value interleaving exported from `draft inspect --include-draft`.
+
+Capability updates deliberately preserve `use`, routes, and outputs. Change
+routes with `set-route`/`branch`, change output bindings with `set-output` or
+`bind`, and change the capability itself by removing and adding the step.
+
 Interrupts preserve explicit request and resume contracts:
 
 ```bash

docs/wf_mcp_operator_manual.md

@@ -157,6 +157,8 @@ Focused repair helpers:
 - `wf.workflow.set_step_output_map`
 - `wf.workflow.set_workflow_output_bindings`
 - `wf.workflow.set_workflow_output_map` (compatibility-only map adapter)
+- `wf.workflow.add_step_from_capability`
+- `wf.workflow.update_capability_step`
 
 These helpers are deliberately narrow. Prefer them over JSON Patch when the
 caller only needs to edit one common field.
@@ -173,6 +175,21 @@ or repeated-source fan-out.
 The equivalent JSON-RPC operation is
 `workflow.draft_workspaces.set_workflow_output_bindings`.
 
+`wf.workflow.add_step_from_capability` accepts metadata and either the legacy
+`input_map` or the preferred ordered `input_bindings` list. Canonical bindings
+may interleave graph paths and literal values.
+
+`wf.workflow.update_capability_step` accepts a presence-aware `update` object.
+Omitted keys are preserved; explicit `null` clears `desc`, `retry`, or
+`timeout_seconds`. Supplying `input` replaces the complete canonical input
+list, while `input: null` is rejected. The operation preserves `use`, routes,
+and outputs.
+
+Equivalent JSON-RPC operations:
+
+- `workflow.draft_workspaces.add_step_from_capability`
+- `workflow.draft_workspaces.update_capability_step`
+
 Advanced workspace tools:
 
 - `wf.workflow.list_draft_workspaces`: find mutable draft sessions.

docs/workflow_capabilities.md

@@ -227,6 +227,34 @@ Others should be authored and saved:
 
 The platform should support both.
 
+## Capability Steps In Drafts
+
+A capability-backed draft step records its selected capability in `use`, plus
+metadata, canonical input bindings, output bindings, and routes. Creation can
+set these common fields in one revision-checked operation:
+
+```bash
+wf draft add capability report --revision 3 --step publish \
+  --capability local.report.publish \
+  --description "Publish report" --retry 2 --timeout-seconds 30 \
+  --input state.report.title=request.title \
+  --value request.format='"markdown"' --route ok=__end__
+```
+
+Focused update changes only fields explicitly supplied by the caller. Omitted
+metadata is preserved; explicit null through JSON-RPC/MCP, or the matching CLI
+`--clear-*` flag, removes that override. Supplying canonical input bindings
+replaces the complete ordered list atomically. This update preserves `use`,
+routes, and outputs. Use their dedicated operations, or remove/add when
+changing the selected capability.
+
+The transport operation names are:
+
+- JSON-RPC: `workflow.draft_workspaces.add_step_from_capability`
+- JSON-RPC: `workflow.draft_workspaces.update_capability_step`
+- MCP: `wf.workflow.add_step_from_capability`
+- MCP: `wf.workflow.update_capability_step`
+
 ## Authoring Loop
 
 A client authoring workflows, including an LLM client, should be able to:

docs/workflow_drafts.md

@@ -727,6 +727,13 @@ wf draft set-workflow-output <workspace_id> --revision <n> \
 wf draft set-workflow-output <workspace_id> --revision <n> --clear
 wf draft set-workflow-output <workspace_id> --revision <n> \
   --merge --map state.other=other
+wf draft add capability report --revision 3 --step publish \
+  --capability local.report.publish --description "Publish report" \
+  --retry 2 --timeout-seconds 30 \
+  --input state.report.title=request.title \
+  --value request.format='"markdown"' --route ok=__end__
+wf draft update capability report --revision 4 --step publish \
+  --clear-description --retry 0 --clear-timeout
 wf draft branch <workspace_id> --revision <n> --step <step_id> --route ok=__end__ --route error=tool_error
 wf draft handle <workspace_id> --revision <n> --to fail --branch lookup:error --branch transform:error
 wf draft compile <workspace_id>
@@ -750,6 +757,17 @@ may project their declared source schema into missing nested output fields.
 The compatibility `--merge --map` form remains available only for lossy map
 edits and cannot preserve literals, order, or repeated-source fan-out.
 
+`add capability` accepts metadata plus ordered path and literal input bindings.
+`update capability` is presence-aware: omitted fields remain unchanged, while
+`--clear-description`, `--clear-retry`, and `--clear-timeout` remove only the
+selected metadata. Any `--input`/`--value` update replaces the complete input
+list; `--clear-input` writes an empty list. Use `--bindings-file` when path and
+literal records must retain their exact interleaving.
+
+The focused update preserves the step's `use`, routes, and outputs. Route and
+output changes remain separate focused operations. Replacing `use` is not an
+update operation; remove and re-add the capability step explicitly.
+
 Use `draft patch` when these focused commands do not cover the structural edit.
 
 Drafts are not raw workflow plans. Drafts use `steps`, `routes`, and step field