[Doc]Clarify ray.shutdown() behavior for local vs remote clusters

doc/source/ray-core/starting-ray.rst

@@ -78,6 +78,13 @@ Calling ``ray.init()`` starts a local Ray instance on your laptop/machine. This
 
 When the process calling ``ray.init()`` terminates, the Ray runtime will also terminate. To explicitly stop or restart Ray, use the shutdown API.
 
+.. note::
+
+  The behavior of ``ray.shutdown()`` depends on how the cluster was initialized:
+
+  * If ``ray.init()`` started a new local cluster, ``ray.shutdown()`` will terminate all the local Ray processes.
+  * If you connected to an existing cluster (e.g., via ``ray.init(address="auto")`` or ``ray.init(address="ray://<ip>:<port>")``), ``ray.shutdown()`` only disconnects the client -- it does **not** shut down the remote cluster.
+
 .. tab-set::
 
     .. tab-item:: Python

python/ray/_private/worker.py

@@ -2070,6 +2070,23 @@ def shutdown(_exiting_interpreter: bool = False):
     need to redefine them. If they were defined in an imported module, then you
     will need to reload the module.
 
+    .. note::
+
+        The behavior of ``ray.shutdown()`` differs depending on how the cluster
+        was initialized:
+
+        * If a new local Ray cluster was started by ``ray.init()`` (i.e., no
+          ``address`` argument was provided and no existing cluster was found,
+          or ``address="local"`` was explicitly used), ``ray.shutdown()`` will
+          terminate all the local Ray processes (raylet, object store, etc.)
+          that were spawned by ``ray.init()``.
+
+        * If you connected to an existing cluster (e.g., via
+          ``ray.init(address="auto")`` or ``ray.init(address="ray://<ip>:<port>")``),
+          ``ray.shutdown()`` will only disconnect the client from the cluster.
+          It will **not** shut down the remote cluster. The cluster will
+          continue running and can be connected to again.
+
     Args:
         _exiting_interpreter: True if this is called by the atexit hook
             and false otherwise. If we are exiting the interpreter, we will