docs pass

docs/README.md

@@ -40,19 +40,21 @@ implementation plans are kept for context, not as active instructions.
 
 ## MCP Platform
 
-- [`wf_mcp_operator_manual.md`](wf_mcp_operator_manual.md): operator/client
-  guide for connections, catalog discovery, drafts, artifacts, deployments, and
-  troubleshooting flow.
-- [`wf_mcp_end_to_end_runbook.md`](wf_mcp_end_to_end_runbook.md): full run from
-  connection setup to capability discovery to deployment execution.
+- [`wf_mcp_operator_manual.md`](wf_mcp_operator_manual.md): start here for
+  the MCP-facing workflow lifecycle and tool families.
+- [`wf_mcp_end_to_end_runbook.md`](wf_mcp_end_to_end_runbook.md): concrete
+  tool-call runbook from capability discovery through deployment, run, resume,
+  and cleanup.
+- [`wf_mcp_troubleshooting.md`](wf_mcp_troubleshooting.md): diagnostics and
+  repair steps for source, deployment, run, and resume failures.
+- [`durable_run_operations.md`](durable_run_operations.md): durable run
+  records, compact inspection, bounded traces, and resume semantics.
 - [`wf_mcp_capability_sources.md`](wf_mcp_capability_sources.md): source model
   for raw capabilities, workflow-ready node specs, admin tools, and docs.
 - [`workflow_capabilities.md`](workflow_capabilities.md): distinction between
   raw capabilities, workflow capabilities, wrappers, artifacts, and deployments.
 - [`wf_mcp_proxy_reality_and_roadmap.md`](wf_mcp_proxy_reality_and_roadmap.md):
   practical proxy behavior, FastMCP gaps, and local workaround boundaries.
-- [`wf_mcp_troubleshooting.md`](wf_mcp_troubleshooting.md): common MCP/server
-  failure modes.
 
 ## Protocol Notes
 

docs/durable_run_operations.md

@@ -131,8 +131,9 @@ the core rule that external callers resume by `run_id`.
 ## Debugging Rules For LLM Clients
 
 - Always capture `run_id` from `run_deployment`.
-- Prefer `inspect_run` before reading trace detail.
-- Use `read_run_trace` with explicit small ranges.
+- Use `inspect_run` for compact stopped-run summaries.
+- Use `read_run_trace` only when trace entries are needed, and always request a
+  bounded `trace_range`.
 - Treat `trace_count` as metadata, not an instruction to fetch the entire trace.
 - If a run failed with `trace_count: 0`, read the top-level `error` first; the
   failure may have happened before any trace entry could be emitted.
@@ -141,6 +142,20 @@ the core rule that external callers resume by `run_id`.
 - If the run failed because a live source errored during execution, do not retry
   through `resume_run`; start a new run after repairing the source/problem.
 
+## Deployment Deletion Boundary
+
+`wf.workflow.delete_deployment` removes the mutable deployment binding. It does
+not delete:
+
+- immutable workflow artifacts
+- wrapper artifacts
+- stored run records
+- run checkpoints
+
+Existing run records keep the pinned deployment and artifact environment captured
+at run time. Deleting a deployment prevents future runs through that deployment
+id, but it does not erase historical stopped-run inspection data.
+
 ## Current Limits
 
 - No mid-call crash recovery.

docs/wf_mcp_end_to_end_runbook.md

@@ -28,6 +28,28 @@ demo.personal.echo_tool
 The saved artifact uses the logical source alias `demo`, so the same workflow can
 later be deployed against `demo.work` or another compatible account.
 
+## Minimal Lifecycle Summary
+
+The shortest dependable lifecycle is:
+
+```text
+list_capabilities
+inspect_capability
+create_draft_workspace_from_capability
+patch_draft_workspace
+validate_draft_workspace
+create_artifact_from_workspace
+save_deployment
+validate_deployment
+run_deployment
+inspect_run or read_run_trace only when needed
+resume_run only when status is interrupted
+delete_deployment for temporary deployments
+```
+
+Do not expect a newly saved workflow to appear as a new MCP tool in an existing
+client session. Use `run_deployment` and `call_capability` as stable front doors.
+
 ## 0. Know The Three Names
 
 This example deliberately uses three related names:
@@ -364,7 +386,32 @@ Validation catches problems such as:
 
 - a bound source is disabled or missing
 - a required capability disappeared
-- the saved dependency schema snapshot drifted from the live capability
+- the saved dependency schema drifted from the live capability
+
+### Optional Live Source Check
+
+Use this before a real run when you need to know whether the bound upstream
+source can currently answer.
+
+```yaml
+tool: wf.workflow.validate_deployment
+arguments:
+  deployment_id: "echo.personal"
+  live_check: true
+```
+
+Expected successful shape:
+
+```json
+{
+  "deployment_id": "echo.personal",
+  "status": "runnable",
+  "diagnostics": []
+}
+```
+
+If a bound upstream source is down, expect `status="unrunnable"` and a diagnostic
+with `code="source_unreachable"`.
 
 ## 9. Run The Deployment
 
@@ -713,3 +760,22 @@ outcome propagation belongs in `wf_core` subgraph support.
 
 See `examples/mcp_wrapper_authoring_flow.py` for this same sequence through the
 Python handler layer.
+
+### Cleanup Temporary Deployments
+
+Temporary test deployments can be removed without touching immutable artifacts.
+
+```yaml
+tool: wf.workflow.delete_deployment
+arguments:
+  deployment_id: "echo.personal"
+```
+
+Expected:
+
+```json
+{
+  "deployment_id": "echo.personal",
+  "deleted": true
+}
+```

docs/wf_mcp_operator_manual.md

@@ -188,6 +188,11 @@ Primary:
 - `wf.workflow.inspect_deployment`: inspect source bindings for one saved
   deployment.
 - `wf.workflow.validate_deployment`: check dependency availability and drift.
+  By default, validates against the broker's current source inventory and saved
+  catalog snapshots. This is cheap and side-effect-light. Pass `live_check=true`
+  only when you explicitly want to contact each required upstream source. A live
+  check may spawn stdio MCP servers or perform network I/O. Live-check failures
+  are returned as `source_unreachable` diagnostics.
 - `wf.workflow.run_deployment`: execute a saved deployment with input. The
   default response is compact and returns `trace_count`; pass `trace_range`
   only when debugging a failed or surprising run.
@@ -196,6 +201,7 @@ Primary:
   slice for a durable run.
 - `wf.workflow.resume_run`: resume an interrupted durable run when its pinned
   dependencies remain available.
+- `wf.workflow.delete_deployment`: remove one mutable deployment binding.
 
 Advanced:
 
@@ -206,6 +212,9 @@ Advanced:
 caller already has a trusted compiled raw workflow plan or is deliberately
 testing the lower-level artifact boundary.
 
+`delete_deployment` removes the saved deployment binding only. It does not delete
+workflow artifacts, wrapper artifacts, or run checkpoints.
+
 ### `wf.docs`
 
 Local documentation source.
@@ -394,6 +403,33 @@ The detailed run contract is documented in
 capture `run_id`, inspect summaries first, read bounded trace slices only when
 debugging, and resume only runs that are actually interrupted.
 
+## Primary Workflow Lifecycle
+
+Use this path when an LLM client needs to build, test, and run a saved workflow.
+
+1. Discover workflow-ready capabilities with `wf.workflow.list_capabilities`.
+2. Inspect the selected capability with `wf.workflow.inspect_capability`.
+3. Create a patchable draft with
+   `wf.workflow.create_draft_workspace_from_capability`.
+4. Patch the draft with `wf.workflow.patch_draft_workspace`.
+5. Validate the draft with `wf.workflow.validate_draft_workspace`.
+6. Save an immutable workflow or wrapper artifact with
+   `wf.workflow.create_artifact_from_workspace` or
+   `wf.workflow.create_wrapper_from_workspace`.
+7. Save a mutable deployment with `wf.workflow.save_deployment`.
+8. Validate the deployment with `wf.workflow.validate_deployment`.
+9. Optionally call `wf.workflow.validate_deployment` with `live_check=true`
+   before a real run.
+10. Run with `wf.workflow.run_deployment`.
+11. If the run returns `interrupted`, resume with `wf.workflow.resume_run`.
+12. Inspect stopped runs with `wf.workflow.inspect_run`; read bounded trace
+    slices with `wf.workflow.read_run_trace`.
+13. Delete temporary deployments with `wf.workflow.delete_deployment`.
+
+Artifacts are immutable saved definitions. Deployments are mutable environment
+bindings. Runs are durable stopped execution records. Deleting a deployment does
+not delete artifacts or existing run records.
+
 ## Which Tool Do I Use?
 
 | I want to... | Use |
@@ -421,6 +457,7 @@ debugging, and resume only runs that are actually interrupted.
 | Check whether a deployment can run | `wf.workflow.validate_deployment` |
 | Execute a saved workflow | `wf.workflow.run_deployment` |
 | Inspect a stopped workflow run | `wf.workflow.inspect_run` |
+| Delete a temporary deployment binding | `wf.workflow.delete_deployment` |
 | Read bounded debug trace entries | `wf.workflow.read_run_trace` |
 | Resume an interrupted workflow run | `wf.workflow.resume_run` |
 

docs/wf_mcp_troubleshooting.md

@@ -282,6 +282,28 @@ Current drift policies:
 
 Prefer `block` unless a human has actually reviewed the changed contract.
 
+## `validate_deployment(live_check=true)` Says `source_unreachable`
+
+Meaning: static deployment validation found a matching saved source/catalog, but
+the live upstream source could not answer when contacted.
+
+Common causes:
+
+- stdio MCP server command is missing or exits during startup
+- network MCP server is offline
+- auth/config changed outside the broker
+- source process starts too slowly and hits the live-check timeout
+
+What to do:
+
+1. Check the connection with `wf.admin.get_connection_statuses`.
+2. Refresh or reload the config if the source was recently enabled.
+3. Fix the source command/auth/network outside the workflow artifact.
+4. Run `wf.workflow.validate_deployment` again with `live_check=true`.
+
+Do not fix this by editing the workflow artifact unless the source capability
+itself changed. This is an environment problem, not workflow business logic.
+
 ## `run_deployment` Returns `unrunnable`
 
 `run_deployment` validates dependencies before execution. If blocking
@@ -398,6 +420,22 @@ wf.admin.inspect_source
 If the source has tools but no prompts/resources, that may be completely valid.
 MCP servers are not required to implement every capability family.
 
+## Test Deployment Clutter
+
+Symptom: `wf.workflow.list_deployments` shows temporary deployments from earlier
+tests or LLM attempts.
+
+Use:
+
+```yaml
+tool: wf.workflow.delete_deployment
+arguments:
+  deployment_id: "test_alias_check"
+```
+
+This deletes only the mutable deployment binding. Saved artifacts and durable run
+records remain.
+
 ## What To Capture In A Bug Report
 
 For a control-plane discovery bug:

tests/wf_mcp/server/test_docs.py

@@ -32,6 +32,9 @@ def test_server_exposes_platform_documentation_resources() -> None:
             result = await client.read_resource("wf://docs/operator-manual")
             assert isinstance(result[0], mcp_types.TextResourceContents)
             assert "wf_mcp Operator Manual" in result[0].text
+            assert "Primary Workflow Lifecycle" in result[0].text
+            assert "live_check" in result[0].text
+            assert "delete_deployment" in result[0].text
 
     asyncio.run(run_proxy())