subgraph support in wf_authoring

docs/authoring_sketch.md

@@ -247,7 +247,17 @@ it.
 
 ### `Workflow -> NodeSpec`
 
-In the future, a compiled workflow or subgraph can be wrapped as a reusable
+Today there are two different authoring paths:
+
+- `subgraph_node` / `async_subgraph_node` wrap a compiled workflow as a normal
+  `NodeSpec`. The parent sees one node call and child frames/interrupts are not
+  native parent state.
+- `subgraph_ref` builds a native `SubgraphNode` contract from a compiled
+  `Workflow`: child input schema, output schema, and workflow outcomes are
+  copied into the boundary. Runtime execution still raises until native
+  subgraph scopes are implemented.
+
+In the future, a compiled workflow or subgraph can also be exposed as a reusable
 `NodeSpec`, likely by treating workflow input and output schemas as the node's
 input and output schemas.
 

docs/superpowers/specs/2026-05-24-native-subgraphs-design.md

@@ -303,6 +303,22 @@ resolved dependency set.
 `wf_authoring` should expose native subgraph use separately from wrapper-node
 composition.
 
+Current helper:
+
+```python
+child = subgraph_ref(
+    id="run_child",
+    workflow=child_builder.compile(),
+    input=[input_from(state_path("request"), "request")],
+    output=[output_to("summary", state_path("child_summary"))],
+)
+```
+
+This copies the compiled child workflow contract into a core `SubgraphNode` but
+does not make the child executable yet. `workflow` is still a string reference
+inside the core model; higher layers need a structural workflow reference before
+saved/deployed workflow dependencies become stable.
+
 Possible API:
 
 ```python