code review

src/wf_cli/commands/drafts.py

@@ -177,7 +177,7 @@ def save_draft(
                 version=version,
                 title=title,
                 outcomes=tuple(outcome or ["ok"]),
-                kind="workflow",
+                kind=kind,
                 description=description,
                 source_bindings=source_bindings or None,
             )

src/wf_cli/explain/entries.py

@@ -19,7 +19,7 @@ EXPLAIN_CARDS: tuple[ExplainCard, ...] = (
             "Run `wf deploy validate <deployment_id> --live` after changing bindings.",
         ],
         related_docs=[
-            "docs/wf_cli_usage.md#deployment-validation",
+            "docs/superpowers/specs/2026-06-01-wf-cli-design.md",
             "docs/workflow_capabilities.md",
         ],
     ),
@@ -38,8 +38,8 @@ EXPLAIN_CARDS: tuple[ExplainCard, ...] = (
             "Run `wf deploy validate <deployment_id> --live` again after fixing the source.",
         ],
         related_docs=[
-            "docs/wf_cli_usage.md#deployment-validation",
-            "docs/wf_mcp_unified_proxy_plan.md",
+            "docs/wf_mcp_operator_manual.md",
+            "docs/wf_mcp_proxy_reality_and_roadmap.md",
         ],
     ),
     ExplainCard(
@@ -57,7 +57,7 @@ EXPLAIN_CARDS: tuple[ExplainCard, ...] = (
             "Use `wf deploy validate <deployment_id>` to confirm the binding set.",
         ],
         related_docs=[
-            "docs/wf_cli_usage.md#save-and-validate-a-deployment",
+            "docs/workflow_artifacts.md",
             "docs/workflow_capabilities.md#sources",
         ],
     ),
@@ -77,7 +77,7 @@ EXPLAIN_CARDS: tuple[ExplainCard, ...] = (
         ],
         related_docs=[
             "docs/workflow_capabilities.md",
-            "docs/wf_cli_usage.md#capability-discovery",
+            "docs/superpowers/specs/2026-06-01-wf-cli-design.md",
         ],
     ),
     ExplainCard(
@@ -114,7 +114,7 @@ EXPLAIN_CARDS: tuple[ExplainCard, ...] = (
             "Re-run validation before starting the deployment.",
         ],
         related_docs=[
-            "docs/wf_cli_usage.md#deployment-validation",
+            "docs/wf_mcp_end_to_end_runbook.md",
             "docs/current_roadmap.md",
         ],
     ),

src/wf_cli/explain/models.py

@@ -9,10 +9,11 @@ class ExplainCard(BaseModel):
     code: str = Field(min_length=1, description="Stable diagnostic or CLI error code.")
     summary: str = Field(min_length=1, description="One-sentence explanation.")
     why_it_happens: list[str] = Field(
-        description="Common causes, ordered from most likely to least likely."
+        min_length=1,
+        description="Common causes, ordered from most likely to least likely.",
     )
     how_to_fix: list[str] = Field(
-        description="Concrete next steps an agent or user can try."
+        min_length=1, description="Concrete next steps an agent or user can try."
     )
     related_docs: list[str] = Field(
         default_factory=list,

src/wf_cli/explain/parser.py

@@ -13,7 +13,7 @@ def parse_explain_input(raw: str) -> list[str]:
     stripped = raw.strip()
     if not stripped:
         raise ExplainInputError("explain input is empty")
-    if stripped.startswith("{") or stripped.startswith("["):
+    if stripped.startswith(("{", "[")):
         try:
             value = json.loads(stripped)
         except json.JSONDecodeError as exc:

src/wf_cli/formats.py

@@ -24,9 +24,17 @@ def render_list_payload(
     """Render a handler list payload without changing the JSON contract."""
     if output_format is ListOutputFormat.JSON:
         return json.dumps(payload, indent=2, sort_keys=True)
-    items = payload.get(collection_key, [])
+    if collection_key not in payload:
+        raise ValueError(
+            f"list payload missing required field {collection_key!r}: "
+            f"available fields are {sorted(payload)}"
+        )
+    items = payload[collection_key]
     if not isinstance(items, list):
-        raise ValueError(f"list payload missing array field {collection_key!r}")
+        raise ValueError(
+            f"list payload field {collection_key!r} must be an array, "
+            f"got {type(items).__name__}"
+        )
     if output_format is ListOutputFormat.IDS:
         return "\n".join(_item_id(item, id_field=id_field) for item in items)
     return "\n".join(

src/wf_cli/io.py

@@ -52,6 +52,8 @@ def parse_bindings(bindings: list[str]) -> dict[str, str]:
         logical, separator, concrete = item.partition("=")
         if separator != "=" or not logical or not concrete:
             raise CliInputError("--binding must use logical=concrete")
+        if logical in parsed:
+            raise CliInputError(f"duplicate --binding for {logical!r}")
         parsed[logical] = concrete
     return parsed