Add opt-in debug logging across the CLI pipeline

Thread RP_DEBUG-driven logging through input, detection, rendering, and pager decisions so CLI behavior is inspectable without polluting stdout. Add focused coverage for debug wiring, env parsing, and stderr-only output.

src/rp/render.py

@@ -10,6 +10,7 @@ from rich.markdown import Markdown
 from rich.padding import Padding
 from rich.syntax import Syntax
 
+from rp.debug import DebugLogger, log_debug
 from rp.pager import MousePager
 
 
@@ -21,11 +22,13 @@ class RenderOptions:
         theme: Pygments color theme name.
         line_numbers: Show line numbers. ``None`` enables them for code only.
         pager: Use pager for output. ``None`` auto-detects terminal output.
+        debug: Optional debug logger for render and pager decisions.
     """
 
     theme: str = "monokai"
     line_numbers: bool | None = None
     pager: bool | None = None
+    debug: DebugLogger | None = None
 
 
 _MARKDOWN_TYPES: set[str] = {"markdown", "md"}
@@ -49,12 +52,27 @@ def render(
     line_numbers = options.line_numbers
     if line_numbers is None:
         line_numbers = file_type not in _MARKDOWN_TYPES and file_type not in _JSON_TYPES
+        log_debug(
+            options.debug,
+            f"render: auto-set line_numbers={line_numbers} for {file_type!r}",
+        )
 
     use_pager = options.pager
     if use_pager is None:
         import sys
 
-        use_pager = sys.stdout.isatty()
+        stdout_is_tty = sys.stdout.isatty()
+        use_pager = stdout_is_tty
+        log_debug(
+            options.debug,
+            f"pager: auto-detected {'enabled' if use_pager else 'disabled'} "
+            f"because stdout is {'a' if stdout_is_tty else 'not a'} TTY",
+        )
+    else:
+        log_debug(
+            options.debug,
+            f"pager: explicitly {'enabled' if use_pager else 'disabled'}",
+        )
 
     renderable: RenderableType
     if file_type in _MARKDOWN_TYPES:
@@ -63,6 +81,7 @@ def render(
         try:
             renderable = RichJSON(content)
         except (SyntaxError, ValueError):
+            log_debug(options.debug, "render: invalid JSON, falling back to syntax")
             renderable = Syntax(
                 content, "json", theme=options.theme, line_numbers=line_numbers
             )
@@ -72,6 +91,10 @@ def render(
                 content, file_type, theme=options.theme, line_numbers=line_numbers
             )
         except Exception:
+            log_debug(
+                options.debug,
+                f"render: unknown lexer {file_type!r}, falling back to plain text",
+            )
             renderable = Syntax(
                 content, "text", theme=options.theme, line_numbers=line_numbers
             )
@@ -79,7 +102,9 @@ def render(
     padded = Padding(renderable, (1, 2))
 
     if use_pager:
-        with console.pager(pager=MousePager(), styles=True):
+        log_debug(options.debug, "pager: opening pager")
+        with console.pager(pager=MousePager(debug=options.debug), styles=True):
             console.print(padded)
     else:
+        log_debug(options.debug, "pager: writing directly to the console")
         console.print(padded)