docs: documented the variable shadowing validator

Graph-Agents.md

@@ -137,7 +137,10 @@ nodes:
   parameter (see [Passing Agent Variables at Spawn](Agents#passing-agent-variables-at-spawn)).
   Declared variables are seeded into the initial graph state automatically
   (resolved value first, then declared default), so `{{name}}` resolves
-  inside `llm` node prompts with no setup script required.
+  inside `llm` node prompts with no setup script required. Seeding never
+  overwrites an explicit `initial_state:` key. A declared variable sharing a
+  name with one is *shadowed* (the `initial_state` value wins), and the graph
+  validator emits a warning naming each shadowed variable.
 - **`can_spawn_agents` is declared, or derived when omitted.** When the key
   is absent, a graph agent can spawn dynamic child agents iff its graph
   contains at least one `agent` node; an explicit value overrides that