fix: add draft route repair guidance

src/wf_api/draft_authoring.py

@@ -430,11 +430,23 @@ class WorkflowDraftAuthoringApi:
                     f"missing_outcomes={sorted(missing_outcomes)!r}",
                     f"unknown_outcomes={sorted(unknown_outcomes)!r}",
                 ]
+                repairs: list[str] = []
+                if unknown_outcomes:
+                    repairs.append(
+                        f"remove --route entries for {sorted(unknown_outcomes)!r}"
+                    )
+                if missing_outcomes:
+                    repairs.append(
+                        f"add --route OUTCOME=TARGET for {sorted(missing_outcomes)!r}"
+                    )
                 raise ValueError(
                     f"capability {capability_name!r} declares outcomes "
-                    f"{declared_outcomes}, but routes has "
+                    f"{declared_outcomes}, but routes has missing routes "
-                    f"missing routes {sorted(missing_outcomes)} and unknown "
+                    f"{sorted(missing_outcomes)} and unknown routes "
-                    f"routes {sorted(unknown_outcomes)}; " + ", ".join(details)
+                    f"{sorted(unknown_outcomes)}; "
+                    + ", ".join(details)
+                    + "; repair: "
+                    + "; ".join(repairs)
                 )
             step_routes = dict(routes)
         else:

tests/wf_api/test_drafts_service.py

@@ -1016,7 +1016,7 @@ async def test_add_step_from_capability_rejects_unknown_routes_for_multi_outcome
         draft=_echo_draft(),
     )
 
-    with pytest.raises(ValueError, match="unknown routes"):
+    with pytest.raises(ValueError, match="unknown routes") as exc_info:
         await authoring.add_step_from_capability(
             workspace_id="unknown_multi",
             revision=1,
@@ -1025,6 +1025,39 @@ async def test_add_step_from_capability_rejects_unknown_routes_for_multi_outcome
             routes={"ok": "__end__", "skipped": "__end__", "typo": "__end__"},
         )
 
+    message = str(exc_info.value)
+    assert "declares outcomes ('ok', 'skipped')" in message
+    assert "unknown routes ['typo']" in message
+    assert "remove --route entries for ['typo']" in message
+
+
+@pytest.mark.asyncio
+async def test_add_step_rejects_unknown_single_outcome_route_with_repair(
+    tmp_path: Path,
+) -> None:
+    artifact_store = FileWorkflowArtifactStore(
+        tmp_path / "drafts_unknown_single_outcome"
+    )
+    api, _service, authoring = _draft_api(artifact_store, register_echo=True)
+    await api.create_draft_workspace(
+        workspace_id="unknown_single",
+        draft=_echo_draft(),
+    )
+
+    with pytest.raises(ValueError) as exc_info:
+        await authoring.add_step_from_capability(
+            workspace_id="unknown_single",
+            revision=1,
+            step_id="second",
+            capability_name="demo.personal.echo_tool",
+            routes={"ok": "__end__", "error": "fail"},
+        )
+
+    message = str(exc_info.value)
+    assert "declares outcomes ('ok',)" in message
+    assert "unknown routes ['error']" in message
+    assert "remove --route entries for ['error']" in message
+
 
 # -- Draft remove helpers --