examples, docs, ergonomics and code review fixes

docs/current_roadmap.md

@@ -57,6 +57,8 @@ implementation state.
   subgraph boundary. Saved/deployed child resolution remains next. Wrapper
   helpers currently run child workflows as ordinary nodes; native
   `SubgraphNode` is now the graph-as-node path for prepared children.
+  `WorkflowBuilder.prepare_subgraph()` and `WorkflowBuilder.resume()` make the
+  local runnable/resumable path available without core-runtime plumbing.
 - **Concurrent foreach**: implemented in core with explicit scheduling,
   reducer/merge semantics, item error policy, async handler batching, and
   quiescent interrupt behavior. Remaining work is polish and future reuse of

docs/wf_core_architecture.md

@@ -140,14 +140,17 @@ limits and intended adapter seam.
   and lineage; child output commits only through declared boundary bindings and
   the parent routes by the child's terminal workflow outcome. Saved/deployed
   workflow resolution remains outside core and is not implemented at this
-  boundary yet.
+  boundary yet. For local authoring, `WorkflowBuilder.prepare_subgraph()`
+  registers a child builder and `WorkflowBuilder.resume()` continues a paused
+  prepared-child interrupt without requiring direct core-runtime calls.
 - The current `wf_authoring` wrapper helpers still run child workflows as
   ordinary sync or async nodes and therefore do not preserve native child
   state or resumable interrupts. Native `SubgraphNode` plus
   `PreparedSubgraph` is the first-class path: prepared child interrupts now
   bubble to the parent run and resume inside the original child scope. See
   `examples/authoring_workflow_as_node.py` for the compatibility wrapper shape
-  and `examples/authoring_native_subgraph.py` for the native path.
+  and `examples/authoring_native_subgraph.py` plus
+  `examples/authoring_native_subgraph_interrupt.py` for the native path.
 - Saved workflow-as-node execution with interrupts still requires platform
   resolution of artifact/deployment references into prepared child
   dependencies before core execution begins.

docs/workflow_artifacts.md

@@ -662,8 +662,10 @@ artifact/deployment resolution into prepared children before core can run it.
 
 See `examples/authoring_workflow_as_node.py` for the compatibility wrapper-node
 approach and `examples/authoring_native_subgraph.py` for native prepared-child
-execution. In the wrapper example the parent trace sees one node call; in the
-native example child trace entries remain in the parent run state.
+execution. `examples/authoring_native_subgraph_interrupt.py` demonstrates a
+native child pause and builder-driven resume. In the wrapper example the
+parent trace sees one node call; in the native examples child trace entries
+remain in the parent run state.
 
 Until that core upgrade exists, artifact tooling must not assume that an
 interrupting saved workflow can safely be used as a child node. Top-level saved