diff --git a/docs/docs/python-sdk/sdk_ref/infrahub_sdk/node/related_node.mdx b/docs/docs/python-sdk/sdk_ref/infrahub_sdk/node/related_node.mdx
index edc1112c..73371c15 100644
--- a/docs/docs/python-sdk/sdk_ref/infrahub_sdk/node/related_node.mdx
+++ b/docs/docs/python-sdk/sdk_ref/infrahub_sdk/node/related_node.mdx
@@ -19,6 +19,12 @@ Base class for representing a related node in a relationship.
 id(self) -> str | None
 ```
 
+Return the parsed peer id without triggering a store lookup.
+
+Returns None when the response carried only hfid_str (no id, no peer)
+— in that case .peer.id would resolve through the store and yield a
+non-None id, so .id and .peer.id are NOT interchangeable.
+
 #### `hfid`
 
 ```python
@@ -95,12 +101,24 @@ fetch(self, timeout: int | None = None) -> None
 peer(self) -> InfrahubNode
 ```
 
+Return the peer node, or raise ValueError if no identifier is available.
+
 #### `get`
 
 ```python
 get(self) -> InfrahubNode
 ```
 
+Return the peer node, performing a store lookup if not materialized.
+
+When resolving via hfid_str the returned node has a non-None id even
+when this RelatedNode's .id is None — that is the case in which
+.peer.id and .id diverge.
+
+**Raises:**
+- `ValueError`: when neither a peer, (_id, _typename), nor hfid_str
+is available.
+
 ### `RelatedNodeSync`
 
 Represents a related node in a synchronous context.
@@ -119,8 +137,21 @@ fetch(self, timeout: int | None = None) -> None
 peer(self) -> InfrahubNodeSync
 ```
 
+Return the peer node, or raise ValueError if no identifier is available.
+
 #### `get`
 
 ```python
 get(self) -> InfrahubNodeSync
 ```
+
+Return the peer node, performing a store lookup if not materialized.
+
+When resolving via hfid_str the returned node has a non-None id even
+when this RelatedNode's .id is None — that is the case in which
+.peer.id and .id diverge.
+
+**Raises:**
+- `ValueError`: when neither a peer, (_id, _typename), nor hfid_str
+is available.
+
diff --git a/infrahub_sdk/node/related_node.py b/infrahub_sdk/node/related_node.py
index 5b46a8f7..baebecdd 100644
--- a/infrahub_sdk/node/related_node.py
+++ b/infrahub_sdk/node/related_node.py
@@ -90,6 +90,12 @@ def __init__(self, branch: str, schema: RelationshipSchemaAPI, data: Any | dict,
 
     @property
     def id(self) -> str | None:
+        """Return the parsed peer id without triggering a store lookup.
+
+        Returns None when the response carried only hfid_str (no id, no peer)
+        — in that case .peer.id would resolve through the store and yield a
+        non-None id, so .id and .peer.id are NOT interchangeable.
+        """
         if self._peer:
             return self._peer.id
         return self._id
@@ -242,9 +248,20 @@ async def fetch(self, timeout: int | None = None) -> None:
 
     @property
     def peer(self) -> InfrahubNode:
+        """Return the peer node, or raise ValueError if no identifier is available."""
         return self.get()
 
     def get(self) -> InfrahubNode:
+        """Return the peer node, performing a store lookup if not materialized.
+
+        When resolving via hfid_str the returned node has a non-None id even
+        when this RelatedNode's .id is None — that is the case in which
+        .peer.id and .id diverge.
+
+        Raises:
+            ValueError: when neither a peer, (_id, _typename), nor hfid_str
+                is available.
+        """
         if self._peer:
             return self._peer  # type: ignore[return-value]
 
@@ -289,9 +306,20 @@ def fetch(self, timeout: int | None = None) -> None:
 
     @property
     def peer(self) -> InfrahubNodeSync:
+        """Return the peer node, or raise ValueError if no identifier is available."""
         return self.get()
 
     def get(self) -> InfrahubNodeSync:
+        """Return the peer node, performing a store lookup if not materialized.
+
+        When resolving via hfid_str the returned node has a non-None id even
+        when this RelatedNode's .id is None — that is the case in which
+        .peer.id and .id diverge.
+
+        Raises:
+            ValueError: when neither a peer, (_id, _typename), nor hfid_str
+                is available.
+        """
         if self._peer:
             return self._peer  # type: ignore[return-value]