docs update, allow some debugging

docs/current_roadmap.md

@@ -14,6 +14,11 @@ on both the current docs and the implementation state.
    - Make the LLM/client path progressive: inspect sources, create a draft,
      patch, validate, compile, save, run.
    - Prefer smaller discovery/inspection responses over one huge payload.
+   - Done: the operator manual now categorizes workflow tools into discovery,
+     draft workspace, stateless draft, artifact/deployment, and raw escape
+     hatch groups.
+   - Next: tighten the actual tool responses around that map so list calls stay
+     compact and inspect/run calls carry the detailed payloads.
 
 3. **Wrapper creation ergonomics**
    - Help create workflow-ready wrappers from raw capabilities.
@@ -37,6 +42,19 @@ on both the current docs and the implementation state.
   and failure policy. Do not model this as plain parallel calls over sync
   handlers.
 
+Frame stress points to solve before either feature:
+
+- `RunState.current_frame_id` currently models one active execution cursor.
+  Parallel foreach likely needs multiple runnable child frames.
+- `ExecutionFrame.metadata` currently carries ad hoc foreach data. Subgraphs and
+  parallel foreach should get typed frame payloads or strongly bounded helper
+  accessors before metadata grows more meanings.
+- Subgraph frames need child workflow identity/version/deployment binding, not
+  just a generic metadata dictionary.
+- `RunState.current_node_id` duplicates the current frame's node id for
+  convenience. Any multi-frame scheduler must either keep that as a selected
+  cursor or replace it with an explicit scheduling view.
+
 ## Why This Order
 
 `wf_core` is now coherent enough for the next bottleneck to be platform and DX:

docs/wf_core_architecture.md

@@ -92,6 +92,12 @@ limits and intended adapter seam.
 - Saved workflow-as-node execution with interrupts requires a core runtime
   upgrade: nested run state, child-frame trace preservation, interrupt bubbling
   with path metadata, and resume back into the child workflow.
+- Frames are currently a serial execution stack. That is enough for root
+  workflow execution, serial foreach, and node-level interrupts, but async
+  parallel foreach and native subgraphs will stress the model. In particular,
+  `RunState.current_frame_id` assumes one active cursor, `ExecutionFrame.metadata`
+  is ad hoc, and subgraph frames will need explicit child workflow/deployment
+  identity.
 - Runtime errors are still ordinary exceptions plus failed run status. A richer
   error payload can be added later, but should be designed as part of trace/run
   state rather than scattered exceptions.

docs/wf_mcp_end_to_end_runbook.md

@@ -392,6 +392,11 @@ Expected shape:
 }
 ```
 
+Do not request trace detail by default. `run_deployment` returns `trace_count`
+as the total original trace length and supports explicit ranged debug reads such
+as `"trace_range": {"start": 0, "limit": 10}`. Trace entries may contain
+resolved inputs, outputs, and state changes.
+
 ## 10. Rebind The Same Artifact Later
 
 If another compatible account appears:
@@ -549,3 +554,151 @@ Concrete MCP sequence:
 `create_wrapper_from_workspace` accepts the same request shape except there is
 no `kind` field. It always saves `kind="wrapper"` and the result is discoverable
 as a workflow capability named `workflow.<artifact_id>.v<version>`.
+
+## Wrapper Happy Path
+
+Use this path when a raw/provider capability is callable but you want a reusable
+workflow-facing wrapper with explicit schemas, outcomes, and bindings.
+
+### 1. Inspect The Source Capability
+
+```yaml
+tool: wf.workflow.inspect_capability
+arguments:
+{
+  "qualified_name": "demo.personal.echo_tool"
+}
+```
+
+The response includes `wrapper_hints`. These hints are scaffolding, not final
+business logic. They suggest draft schemas and basic input/output bindings.
+
+### 2. Create A Draft Workspace From The Capability
+
+```yaml
+tool: wf.workflow.create_draft_workspace_from_capability
+arguments:
+{
+  "request": {
+    "workspace_id": "echo_wrapper_draft",
+    "capability_name": "demo.personal.echo_tool",
+    "name": "echo_wrapper",
+    "title": "Echo Wrapper Draft"
+  }
+}
+```
+
+This creates a mutable, revisioned workspace using the inspected
+`wrapper_hints`.
+
+### 3. Patch Or Validate The Workspace
+
+If the hints are good enough, validate:
+
+```yaml
+tool: wf.workflow.validate_draft_workspace
+arguments:
+{
+  "request": {
+    "workspace_id": "echo_wrapper_draft"
+  }
+}
+```
+
+If one field is wrong, use a focused helper or JSON Patch. For example, change
+one route:
+
+```yaml
+tool: wf.workflow.set_draft_route
+arguments:
+{
+  "request": {
+    "workspace_id": "echo_wrapper_draft",
+    "revision": 1,
+    "step_id": "echo",
+    "outcome": "error",
+    "target": "__end__"
+  }
+}
+```
+
+### 4. Save The Workspace As A Wrapper Artifact
+
+```yaml
+tool: wf.workflow.create_wrapper_from_workspace
+arguments:
+{
+  "request": {
+    "workspace_id": "echo_wrapper_draft",
+    "artifact_id": "echo_wrapper",
+    "version": 1,
+    "title": "Echo Wrapper",
+    "outcomes": ["ok", "error"],
+    "source_bindings": {
+      "demo": "demo.personal"
+    }
+  }
+}
+```
+
+The saved wrapper appears in workflow capability discovery as:
+
+```text
+workflow.echo_wrapper.v1
+```
+
+### 5. Deploy And Test The Wrapper
+
+Saved wrappers that use logical sources need a deployment binding when called:
+
+```yaml
+tool: wf.workflow.save_deployment
+arguments:
+{
+  "deployment": {
+    "id": "echo_wrapper.personal",
+    "artifact_id": "echo_wrapper",
+    "artifact_version": 1,
+    "bindings": {
+      "demo": "demo.personal",
+      "wf.std": "wf.std"
+    }
+  }
+}
+```
+
+Then test the wrapper through the workflow-facing REPL tool:
+
+```yaml
+tool: wf.workflow.call_capability
+arguments:
+{
+  "qualified_name": "workflow.echo_wrapper.v1",
+  "deployment_id": "echo_wrapper.personal",
+  "payload": {
+    "text": "hello"
+  }
+}
+```
+
+Expected shape:
+
+```json
+{
+  "qualified_name": "workflow.echo_wrapper.v1",
+  "kind": "wrapper_artifact",
+  "outcome": "completed",
+  "output": {
+    "echoed": "hello"
+  },
+  "diagnostics": []
+}
+```
+
+Current limitation: saved wrappers are executed through the deployment runtime,
+so `call_capability` reports the wrapper run status (`completed`, `failed`, or
+`interrupted`) rather than remapping inner node outcomes. True graph-as-node
+outcome propagation belongs in `wf_core` subgraph support.
+
+See `examples/mcp_wrapper_authoring_flow.py` for this same sequence through the
+Python handler layer.

docs/wf_mcp_operator_manual.md

@@ -97,6 +97,96 @@ Typical tools:
 - `wf.workflow.validate_deployment`
 - `wf.workflow.run_deployment`
 
+## Workflow Tool Map
+
+The workflow surface is intentionally split by job. Use the primary path first;
+the advanced tools exist for debugging, compatibility, or focused repair.
+
+### Discovery
+
+Primary:
+
+- `wf.workflow.list_capabilities`: compact, paged workflow capability search.
+  It returns names, source ids, outcomes, and top-level field names.
+- `wf.workflow.inspect_capability`: full contract for one selected capability,
+  including schemas, outcomes, and wrapper authoring hints.
+- `wf.workflow.call_capability`: REPL-style direct test of one workflow
+  capability or saved wrapper artifact.
+
+Supporting:
+
+- `wf.workflow.list_artifacts`: compact list of saved workflow and wrapper
+  artifacts.
+- `wf.workflow.inspect_artifact`: full saved artifact payload.
+
+### Draft Workspaces
+
+Primary:
+
+- `wf.workflow.create_draft_workspace_from_capability`: preferred wrapper
+  bootstrap. It inspects one capability, applies its hints, and creates a
+  revisioned draft workspace.
+- `wf.workflow.get_draft_workspace`: fetch current revision and optionally the
+  full draft document.
+- `wf.workflow.validate_draft_workspace`: refresh diagnostics without changing
+  revision.
+- `wf.workflow.create_wrapper_from_workspace`: save a validated draft workspace
+  as a callable wrapper capability.
+- `wf.workflow.create_artifact_from_workspace`: save a validated draft workspace
+  as a full workflow artifact.
+
+Focused repair helpers:
+
+- `wf.workflow.set_draft_name`
+- `wf.workflow.set_draft_route`
+- `wf.workflow.set_step_input_map`
+- `wf.workflow.set_step_output_map`
+
+These helpers are deliberately narrow. Prefer them over JSON Patch when the
+caller only needs to edit one common field.
+
+Advanced workspace tools:
+
+- `wf.workflow.list_draft_workspaces`: find mutable draft sessions.
+- `wf.workflow.patch_draft_workspace`: apply RFC 6902 JSON Patch with revision
+  checking.
+- `wf.workflow.delete_draft_workspace`: cleanup abandoned sessions.
+- `wf.workflow.create_draft_workspace`: store a caller-provided draft directly.
+- `wf.workflow.create_minimal_draft_workspace`: bootstrap around one capability
+  when the caller already knows schemas and bindings.
+
+### Stateless Draft Tools
+
+Use these when the caller can resend the whole draft on every call:
+
+- `wf.workflow.validate_draft`
+- `wf.workflow.compile_draft`
+- `wf.workflow.patch_draft`
+- `wf.workflow.create_artifact_from_draft`
+
+Draft workspaces are usually safer for LLM clients because they avoid a
+rewrite-the-whole-document loop and preserve optimistic-concurrency revisions.
+
+### Artifact And Deployment
+
+Primary:
+
+- `wf.workflow.save_deployment`: bind one saved artifact version to concrete
+  sources.
+- `wf.workflow.validate_deployment`: check dependency availability and drift.
+- `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.
+
+Advanced:
+
+- `wf.workflow.save_artifact`: persist a complete artifact JSON document.
+- `wf.workflow.create_artifact_from_plan`: raw compiled-plan escape hatch.
+
+`create_artifact_from_plan` bypasses draft ergonomics. Use it only when the
+caller already has a trusted compiled raw workflow plan or is deliberately
+testing the lower-level artifact boundary.
+
 ### `wf.docs`
 
 Local documentation source.
@@ -253,6 +343,15 @@ Use `run_deployment` rather than expecting newly saved workflows to appear as
 brand-new MCP tools. Many LLM harnesses do not reliably refresh callable tool
 schemas mid-session.
 
+The default `run_deployment` response is intentionally compact. It includes run
+status, output, diagnostics, and `trace_count`, where `trace_count` is the total
+number of trace entries in the original run. If the caller needs node-level
+debug detail, pass an explicit `trace_range` object such as
+`{"start": 0, "limit": 10}`; otherwise trace entries stay out of the normal
+response. Trace entries may include resolved node inputs, node outputs, and
+state changes, so treat them as debug payloads rather than ordinary list/summary
+data.
+
 ## Which Tool Do I Use?
 
 | I want to... | Use |