docs: document iteration browsing in full-screen peek

Describe the `[` / `]` keys, the bounded iteration history that survives
iteration end, and the deferred-render buffering that protects terminal
scrollback while fullscreen is active.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 2 people

docs/cli.md

@@ -118,7 +118,7 @@ The loop also stops automatically when:
 
 When you run `ralph run` in an interactive terminal, the agent's stdout and stderr stream live to the console by default. Press `p` to silence the stream (useful for quieter loops) and press `p` again to resume it. The default is off whenever the output is not a real terminal (piped, redirected, or captured in CI), so `ralph run ... | cat` is unaffected.
 
-The compact peek panel shows the ten most recent activity lines to keep the terminal tidy. When you need to see earlier activity from the current iteration, press **shift+P** to enter **full-screen peek** — a scrollable view of the entire buffer that takes over the terminal on the alt screen.
+The compact peek panel shows the ten most recent activity lines to keep the terminal tidy. When you need to see earlier activity from the current iteration — or the activity from a previous iteration — press **shift+P** to enter **full-screen peek**, a scrollable view of the entire buffer that takes over the terminal on the alt screen.
 
 Inside full-screen peek:
 
@@ -127,9 +127,10 @@ Inside full-screen peek:
 | `j` / `k` | Scroll one line down / up |
 | `space` / `b` | Page down / page up |
 | `g` / `G` | Jump to the top / bottom (bottom re-enables follow mode) |
+| `[` / `]` | Browse to the previous / next iteration |
 | `q` or `P` | Exit back to the compact view |
 
-Activity keeps streaming into the buffer while you scroll, so follow mode (`G` or scrolling back to the bottom) catches up to the tail. The full-screen view exits automatically when the iteration ends, returning you to the normal terminal.
+Activity keeps streaming into the buffer while you scroll, so follow mode (`G` or scrolling back to the bottom) catches up to the tail. Iteration ends no longer drop you out of the alt screen — the finished iteration moves into a bounded history so you can keep browsing it (and the new live iteration) with `[` / `]`. Status lines and result text printed during the session are buffered and replayed when you exit fullscreen, so the terminal scrollback stays intact.
 
 Live streaming works with line-buffered agents such as Claude Code, OpenAI Codex, Aider, and any other process that writes one line at a time. For Claude running in stream-json mode you'll see the raw JSON events; for other agents you'll see the agent's plain output. Agents that repaint their own terminal UI (full-screen curses or TUI apps) are not supported — ralphify pipes their stdio, so they detect a non-TTY and fall back to plain output.
 

docs/contributing/codebase-map.md

@@ -136,7 +136,7 @@ Events are defined in `_events.py:EventType`, with a corresponding TypedDict pay
 
 Both execution paths in `_agent.py` accept an `on_output_line(line, stream)` callback and drain the agent's stdout/stderr line-by-line — the blocking path uses two background reader threads, and the streaming path forwards each raw line from `_read_agent_stream`. The engine wires this callback to emit `EventType.AGENT_OUTPUT_LINE` events, which the `ConsoleEmitter` renders only while peek is enabled. The `p` keybinding flips that state via `ConsoleEmitter.toggle_peek()`, driven by `KeypressListener` in `_keypress.py`. The listener only activates on a real TTY; in CI or when stdin is piped it silently no-ops.
 
-The compact peek panel (`_IterationPanel` / `_IterationSpinner`) renders the most recent `_MAX_VISIBLE_SCROLL` lines while buffering up to `_MAX_SCROLL_LINES` (`_console_emitter.py`). Shift+P (`FULLSCREEN_PEEK_KEY`) enters a `_FullscreenPeek` view — a Rich `Live` with `screen=True` that renders the full buffer on the alt screen and accepts vim/less-style navigation (`j/k`, `space/b`, `g/G`, `q`). All keys route through a single `ConsoleEmitter.handle_key()` method that owns the keybinding map for both compact and fullscreen modes. Entering fullscreen stops the compact `Live` so only one renderer owns the terminal; exiting (or iteration end) tears the alt screen down and restores the compact panel with its still-growing buffer.
+The compact peek panel (`_IterationPanel` / `_IterationSpinner`) renders the most recent `_MAX_VISIBLE_SCROLL` lines while buffering up to `_MAX_SCROLL_LINES` (`_console_emitter.py`). Shift+P (`FULLSCREEN_PEEK_KEY`) enters a `_FullscreenPeek` view — a Rich `Live` with `screen=True` that renders one iteration's full buffer on the alt screen and accepts vim/less-style navigation (`j/k`, `space/b`, `g/G`, `q`) plus iteration browsing (`[` / `]`, `PREV_ITERATION_KEY` / `NEXT_ITERATION_KEY`). All keys route through a single `ConsoleEmitter.handle_key()` method that owns the keybinding map for both compact and fullscreen modes. Entering fullscreen stops the compact `Live` so only one renderer owns the terminal; iteration end **does not** tear the alt screen down — the finished panel is frozen and moved into a bounded ring buffer (`_iteration_history`, capped at `_MAX_HISTORY_ITERATIONS`), and the user can keep browsing it (or the new live iteration) without leaving fullscreen. `console.print` calls from event handlers that fire while fullscreen is active are buffered into `_deferred_renders` and replayed when the user exits, so terminal scrollback isn't punctured by holes for missed iteration rules and status lines. The `_FullscreenPeek` instance holds a navigator (`_IterationNavigator` protocol — implemented by `ConsoleEmitter`) plus the iteration id it's currently displaying; the source panel is resolved per-render so eviction or freeze transitions are picked up automatically.
 
 ### Credit trailer
 

docs/quick-reference.md

@@ -157,7 +157,7 @@ Each iteration:
 | `Ctrl+C` (once) | Finishes the current iteration gracefully, then stops |
 | `Ctrl+C` (twice) | Force-kills the agent process and exits immediately |
 | `p` | Toggle live peek of the agent's stdout (on by default in an interactive terminal — press to silence, press again to resume) |
-| `P` (shift+p) | Open full-screen peek — scroll the entire activity buffer. `j/k` line, `space/b` page, `g/G` top/bottom, `q` or `P` exits |
+| `P` (shift+p) | Open full-screen peek — scroll the buffer and browse iterations. `j/k` line, `space/b` page, `g/G` top/bottom, `[/]` prev/next iteration, `q` or `P` exits |
 | `-n` limit reached | Stops after the specified number of iterations |
 | `--stop-on-error` | Stops if agent exits non-zero or times out |