docs: clarify platform bindings and python imports

docs/current_roadmap.md

@@ -115,9 +115,10 @@ auth admin are implemented. The next work is polish, not new broad surfaces.
   diagnostics, and the Google Drive MCP caveat.
 - Completed platform source policy: documented fixed-id sources such as `wf.std`
   and `wf.source` are platform sources. They resolve by fixed source id, do not
-  require self-bindings, and deployment validation rejects explicit
+  require self-bindings, and legacy explicit self-bindings such as
-  platform-source bindings as stale configuration. Other `wf.*` namespaces are
+  `wf.std=wf.std` are accepted as no-op compatibility. Deployment validation
-  described by their own source docs/policies.
+  still rejects non-self platform-source bindings as stale configuration. Other
+  `wf.*` namespaces are described by their own source docs/policies.
 - Completed `wf.source.read_resource`: resource refs are inert pass-by-value
   data using `logical_source`; explicit platform helper nodes dereference them
   through runtime/platform context with bounded output.

docs/runbooks/python-source.md

@@ -3,10 +3,16 @@
 This runbook shows how to expose project-local Python `NodeSpec` functions as
 workflow capabilities through `wf-rpc-server`.
 
-Python sources are trusted in-process code. Importing the configured module uses
+Python sources are trusted in-process code. Importing the configured module can
-normal Python import semantics, so top-level module code can run during
+run top-level module code during `wf config validate` and server startup. Keep
-`wf config validate` and server startup. Keep module top-level work small and
+module top-level work small and side-effect free; put real work inside `@node`
-side-effect free; put real work inside `@node` functions.
+functions.
+
+Prefer package-style source modules and package-relative imports. For example,
+use `module: "my_source.ops"` with `from .helpers import ...` inside
+`my_source/ops.py`. Bare local imports such as `import helpers` use Python's
+global import cache and are only best-effort when multiple configured sources
+reuse the same helper/module names.
 
 ## 1. Write `ops.py`
 

docs/source_architecture.md

@@ -104,9 +104,10 @@ source ids. For example, a resource ref should store:
 The deployment binding decides whether `drive` means `drive.personal`,
 `drive.work`, or another concrete source. Platform sources such as `wf.std` and
 `wf.source` are special because their logical source id is also their concrete
-source id, so they do not require deployment bindings. Deployments should not
+source id, so they do not require deployment bindings. Legacy explicit
-bind platform sources explicitly; validation rejects those bindings as stale
+self-bindings such as `wf.std=wf.std` are accepted as no-op compatibility, but
-or misleading configuration.
+new deployments should omit them. Validation rejects non-self platform bindings
+such as `wf.std=custom.std` as stale or misleading configuration.
 
 Runtime dereference is explicit. Passing a resource ref by value does not fetch
 content. A helper capability such as `wf.source.read_resource` receives the ref,
@@ -160,7 +161,8 @@ operator-configured project sources.
 Generated draft workflows may still use built-in helper sources such as
 `wf.std`. Platform sources do not need deployment bindings, so deployment
 examples should bind configured sources only. If validation reports a platform
-source binding, remove it rather than changing the concrete source id.
+source binding, remove it unless it is an old self-binding kept only for
+compatibility.
 
 ## `wf_sources_mcp` Internal Layers
 

docs/source_provider_guide.md

@@ -72,11 +72,15 @@ Python sources expose trusted in-process `NodeSpec` registries:
   "kind": "python",
   "id": "local.ops",
   "path": ".",
-  "module": "ops",
+  "module": "my_source.ops",
   "registry": "registry"
 }
 ```
 
+Package-style modules are preferred. Relative imports inside the configured
+package are source-local; bare local imports use Python's normal global import
+cache and can collide if multiple sources reuse names like `ops` or `helpers`.
+
 For the full runnable flow, see
 [`Python Source Runbook`](runbooks/python-source.md).