gh-131484: Document that a directory or zipfile script stays on sys.path

-P, -I and PYTHONSAFEPATH drop the implicit sys.path[0] entries (current
directory, script directory, empty string), but a directory or zipfile named
as the script argument is still prepended: that entry is used to locate
__main__.py and makes other modules stored in the target importable. The -P
section currently enumerates only the -m, script and -c/REPL cases.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: yhay81

Doc/using/cmdline.rst

@@ -163,10 +163,11 @@ source.
    added to the start of :data:`sys.path` and the ``__main__.py`` file in
    that location is executed as the :mod:`__main__` module.
 
-   :option:`-I` option can  be used to run the script in isolated mode where
-   :data:`sys.path` contains neither the script's directory nor the user's
-   site-packages directory. All ``PYTHON*`` environment variables are
-   ignored, too.
+   :option:`-I` can be used to run the script in isolated mode. For a Python
+   file, the containing directory is then omitted from :data:`sys.path`, as
+   is the user's site-packages directory; a directory or zipfile target
+   remains, as described under :option:`-P`. All ``PYTHON*`` environment
+   variables are ignored, too.
 
    .. audit-event:: cpython.run_file filename
 
@@ -362,6 +363,13 @@ Miscellaneous options
    * ``python -c code`` and ``python`` (REPL) command lines: Don't prepend an
      empty string, which means the current working directory.
 
+   If the script name refers to a directory or zipfile (see
+   :ref:`using-on-interface-options`), the script name is still added to the
+   start of :data:`sys.path`. This also applies when safe-path mode is
+   enabled by :option:`-I` or :envvar:`PYTHONSAFEPATH`. The entry is used to
+   locate ``__main__.py`` and makes other modules stored in the target
+   importable.
+
    See also the :envvar:`PYTHONSAFEPATH` environment variable, and :option:`-E`
    and :option:`-I` (isolated) options.
 

Misc/NEWS.d/next/Documentation/2026-07-29-12-50-00.gh-issue-131484.Xk2mVq.rst

@@ -0,0 +1,2 @@
+Clarify that a directory or zipfile passed as the script argument remains on
+:data:`sys.path` in safe-path and isolated modes.