docs: complete capability step updates

ISSUES.md

@@ -43,10 +43,12 @@
   outcomes list.
 - [x] A focused contract operation replaces workflow input/state/output
   schemas, preserving reducer metadata carried by the supplied state schema.
-- [ ] The dedicated capability-step CLI cannot set `desc`, `retry`,
+- [x] Capability-step creation accepts `desc`, `retry`, `timeout_seconds`, and
-  `timeout_seconds`, or literal inputs at creation, and there is no focused
+  ordered canonical path/literal inputs through Python, JSON-RPC, MCP, and CLI.
-  update-step operation. The generic RPC step payload can represent these
+  The focused update operation preserves `use`, routes, and outputs while
-  fields, but CLI repair still requires remove/re-add or raw patching.
+  changing selected metadata or atomically replacing the complete canonical
+  input list. Changing the capability itself remains an explicit remove/add
+  operation. TypeScript JSON-RPC parity remains tracked below.
 
 ## Draft revision semantics
 

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 \
+  --step publish \
-  --capability local.report.render_markdown_report \
+  --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.report.title=request.title \
-  --input state.title=title \
+  --value request.format='"markdown"'
-  --input state.summary=summary \
+
-  --bind-output markdown=state.markdown \
+wf draft update capability report_ws \
-  --bind-output title=state.title
+  --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

skills/wf-cli/SKILL.md

@@ -197,9 +197,17 @@ Repeat `--input` and `--bind-output` once per mapping. Do not put multiple
 mappings after one flag.
 
 ```bash
-wf draft add capability <workspace_id> --revision <n> --step <step_id> --capability <qualified_name> --input state.title=title --input state.summary=summary --bind-output markdown=state.markdown --bind-output title=state.title
+wf draft add capability <workspace_id> --revision <n> --step <step_id> --capability <qualified_name> --description "Publish report" --retry 2 --timeout-seconds 30 --input state.title=title --value format='"markdown"' --bind-output markdown=state.markdown
+wf draft update capability <workspace_id> --revision <n> --step <step_id> --clear-description --retry 0 --clear-timeout
 ```
 
+For `update capability`, omission preserves a field and `--clear-*` removes
+the selected metadata. Any `--input`/`--value` update replaces the complete
+ordered input list; use `--bindings-file` for exact path/value interleaving or
+`--clear-input` for `[]`. The update preserves `use`, routes, and outputs.
+Use separate focused commands for routes/outputs, and remove/add to change the
+capability.
+
 Use the matching `wf draft add <kind>` command for control steps. `when`,
 `choose`, and `match` embed their targets and do not accept `--route`.
 Interrupt and subgraph commands preserve their explicit schema contracts.

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

@@ -92,6 +92,7 @@ Prefer focused helpers over JSON Patch for common edits:
 - `bind_draft`
 - `add_step`
 - `add_step_from_capability`
+- `update_capability_step`
 - `branch_draft`
 - `handle_draft`
 - `compile_draft_workspace`
@@ -221,7 +222,8 @@ wf draft validate <workspace_id>
 
   Adds a new capability-backed step with explicit route, input bindings, and
   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
+  edge, outgoing edges, canonical path/literal inputs, metadata, 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__`. Multi-outcome
   capabilities require exact route coverage; missing or unknown outcomes are
@@ -236,11 +238,16 @@ wf draft validate <workspace_id>
   workflow input/state schema paths from the nested capability input schema.
 
 ```bash
-wf draft add 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 --input input.other=other --bind-output result=state.result --bind-output title=state.title
+wf draft add capability <workspace_id> --revision <n> --step <step_id> --capability <qualified_name> --description "Publish report" --retry 2 --timeout-seconds 30 --from-step <prev> --from-outcome ok --route ok=__end__ --route error=fail --input input.text=text --value format='"markdown"' --bind-output result=state.result
+wf draft update capability <workspace_id> --revision <n> --step <step_id> --clear-description --retry 0 --clear-timeout
 wf draft validate <workspace_id>
 ```
 
-Repeat `--input` and `--bind-output` once per mapping. Do not write
+Repeat `--input`, `--value`, and `--bind-output` once per binding. Use
+`--bindings-file` for exact canonical path/value ordering. On update, omitted
+fields are preserved and `--clear-*` removes the selected metadata; input
+flags replace the complete input list. The update preserves capability
+selection, routes, and outputs. Do not write
 `--bind-output title=state.title summary=state.summary`; the second mapping is
 an unexpected extra argument because it is not attached to its own flag.
 

skills/wf-workflow/references/workflow-lifecycle.md

@@ -32,10 +32,16 @@ validated, runnable deployment.
    - When adding a new capability-backed step, prefer:
 
      ```bash
-     wf draft add capability ...
+     wf draft add capability ... --description "Step purpose" \
+       --input state.value=request.value --value request.format='"json"'
+     wf draft update capability ... --retry 0 --clear-timeout
      wf draft validate <workspace_id>
      ```
 
+     Capability updates are presence-aware and preserve capability selection,
+     routes, and outputs. Input flags replace the complete canonical input
+     list; use `--bindings-file` for lossless path/value interleaving.
+
      For control flow, use the corresponding typed `wf draft add <kind>`
      command. Use raw `wf draft patch` only when changing structure that no
      focused helper covers.