diff --git a/docs/specification.md b/docs/specification.md
index 4accaad8b..8196cee39 100644
--- a/docs/specification.md
+++ b/docs/specification.md
@@ -20547,7 +20547,10 @@ For `type: graph` actors, the `route` field defines the graph structure:
 | `type` | string | Yes | Node type: `agent`, `tool`, `conditional`, or `subgraph`. |
 | `name` | string | Yes | Human-readable node name. |
 | `description` | string | Yes | Node purpose and behavior. |
-| `config` | object | No | Type-specific configuration (see below). |
+| `config` | object | No | Type-specific configuration (see below). Not used by `subgraph` nodes. |
+| `actor_ref` | string | No | Namespaced actor reference for `subgraph` nodes (e.g., `local/my-sub-actor`). Top-level field — **not** inside `config`. Must follow `namespace/name` format. |
+| `lsp_binding` | object | No | Per-node LSP server binding (optional). |
+| `tool_sources` | array | No | Tool source references for this node (optional). |
 
 **Node type-specific config:**
 
@@ -20556,7 +20559,7 @@ For `type: graph` actors, the `route` field defines the graph structure:
 | `agent` | `model`, `prompt`, `tools` | LLM agent with optional tools |
 | `tool` | `tool_name`, `parameters` | Deterministic tool execution |
 | `conditional` | `conditions[].check`, `conditions[].route_to` | Routes based on state conditions (Python expressions) |
-| `subgraph` | `actor_path` | Embeds another actor as a nested workflow |
+| `subgraph` | *(none — use top-level `actor_ref` field)* | Embeds another actor as a nested workflow. Set `actor_ref: namespace/actor-name` at the node level, not inside `config`. |
 
 **Edge Definition:**