docs: fix misleading debugger support section in README (#1132)

The README showed a plain py_binary with debugpy in deps and
DEBUGPY_WAIT in env, implying this works out of the box. It doesn't —
py_binary's launcher has no debugpy integration, so the env var is
ignored. Users need the py_debuggable_binary macro from
examples/debugger/ which generates a wrapper entrypoint that actually
starts the debugpy listener.

Update the README to clarify that a wrapper is required and point to the
example for the full working setup.

Close #1054

### Changes are visible to end-users: no

### Test plan

- Covered by existing test cases

Co-authored-by: Joshua Bronson <joshua.bronson@chicagotrading.com>

Author: xangcastle

README.md

@@ -368,16 +368,25 @@ the link target on a subset of binaries.
 
 ### Debugger Support (VSCode/PyCharm)
 
-Attach debuggers using `debugpy`:
+Attach DAP-compatible debuggers (VSCode, PyCharm, Neovim, etc.) using
+[debugpy](https://github.com/microsoft/debugpy). This requires a wrapper
+entrypoint that starts a debugpy listener before running your application —
+simply adding `debugpy` to `deps` is not enough.
 
-```starlark
-# In debug mode, wraps the binary with debugpy listener
-py_binary(
-    name = "app_debug",
-    srcs = ["main.py"],
-    deps = ["//:lib", "@pypi//debugpy"],
-    env = {"DEBUGPY_WAIT": "1"},  # Wait for IDE attachment
-)
+See the [complete debugger example](examples/debugger/) for a working
+setup, including a `py_debuggable_binary` macro that handles the wrapper
+generation automatically.
+
+Quick overview:
+
+```sh
+cd examples/debugger
+
+# Start with debugpy listener, wait for IDE to attach:
+DEBUGPY_WAIT=1 bazel run //:app
+
+# Release mode — no debugpy, runs directly:
+bazel run //:app --config=release
 ```
 
 VSCode `launch.json`: