draft workspace: the promised wf_authoring for LLMs

docs/wf_mcp_end_to_end_runbook.md

@@ -483,3 +483,15 @@ wf.workflow.validate_deployment
 - [`workflow_drafts.md`](workflow_drafts.md) for the preferred authoring format
 - [`workflow_artifacts.md`](workflow_artifacts.md) for immutable artifacts,
   deployments, and dependency contracts
+
+## Workspace Variant
+
+If the client is iterating with an LLM, prefer a draft workspace:
+
+1. Create a minimal workspace from the selected capability.
+2. Fetch the workspace by id when context is needed.
+3. Patch it by id and revision.
+4. Save an artifact from the workspace after validation is clean.
+
+This avoids resending the whole draft object every turn. The saved artifact is
+still immutable and should be deployed through the normal deployment path.

docs/wf_mcp_operator_manual.md

@@ -340,3 +340,19 @@ accounts.
 - [`workflow_drafts.md`](workflow_drafts.md) for the preferred authoring format
 - [`workflow_artifacts.md`](workflow_artifacts.md) for immutable artifacts,
   deployments, and saved workflows as future nodes
+
+## Draft Workspace Authoring
+
+Use draft workspaces when a client should iteratively edit one workflow without
+resending the full draft each turn.
+
+| Need | Tool |
+| --- | --- |
+| Start a patchable authoring session | `wf.workflow.create_minimal_draft_workspace` |
+| Fetch current draft workspace | `wf.workflow.get_draft_workspace` |
+| Patch current draft workspace | `wf.workflow.patch_draft_workspace` |
+| Save final workspace as artifact | `wf.workflow.create_artifact_from_workspace` |
+
+Workspace patches are optimistic-concurrency guarded. Pass the current
+`revision` from `get_draft_workspace`; a stale revision returns
+`revision_conflict` and leaves the stored draft unchanged.

docs/workflow_drafts.md

@@ -197,6 +197,29 @@ The workflow MCP surface exposes these draft tools:
 Use `validate_draft` before saving. Use `patch_draft` when an LLM client needs a
 small targeted correction instead of rewriting the whole workflow.
 
+## Draft Workspaces
+
+Stateless draft tools require the caller to resend the whole draft. Draft
+workspaces are the preferred LLM authoring flow when a client will patch a
+workflow over several turns.
+
+The workspace flow is:
+
+1. `wf.workflow.create_minimal_draft_workspace`
+2. `wf.workflow.get_draft_workspace`
+3. `wf.workflow.patch_draft_workspace`
+4. repeat get/patch until valid
+5. `wf.workflow.create_artifact_from_workspace`
+
+Workspaces are mutable and revisioned. Artifacts are immutable and versioned.
+Patch calls must include the current `revision`; stale revisions return
+`revision_conflict` and do not mutate the workspace.
+
+`create_minimal_draft_workspace` is intentionally only a bootstrapper. It wires
+an `error` outcome for naive MCP wrappers only when `error_message_source` is
+provided or a state path can be derived from `output_map`. Provider-specific
+error envelopes still belong in saved wrapper artifacts or follow-up patches.
+
 ## Patching Drafts
 
 `patch_draft` accepts JSON Patch operations.