docs: find in the terminal — ⌘F / ⌘⇧F, and why it reads transcripts

web/src/content/docs/guides/the-shell.mdx

@@ -78,7 +78,9 @@ Launching Ghostty drops you straight into a persistent zellij session called
 | `Super ⇧P` | New pane, **stay here** — inherits cwd with no hop, so you get a shell right inside the worktree |
 | `Super T` | New tab at `$HOME` — born named `~` (fresh tabs are never `Tab #N`) |
 | `Super ⇧T` | New tab at the **focused pane's directory** — with the **same worktree hop** as `Super P` |
-| `Super F` | **Fullscreen** the focused pane — zoom it to fill the tab, tap again to drop back into the tiled layout |
+| `Super F` | **Find** — full-text search over the focused pane, live as you type (see [Finding things](#finding-things)) |
+| `Super ⇧F` | The same overlay, across **every pane** in the session |
+| `Super ⏎` | **Fullscreen** the focused pane — zoom it to fill the tab, tap again to drop back into the tiled layout |
 | `Super R` | **Reload the terminal stack** — gracefully quit/reopen Ghostty, then start a fresh zellij server with the same tabs, panes and working directories; live Claude Code panes resume their exact conversations |
 | `Super Y` | **yazi peek** — a floating browser with live previews; `Enter` on a directory opens a new tab there |
 | `Super ⇧Y` | **yazi jump** — browse, then drop a shell in the landing directory |
@@ -101,6 +103,37 @@ terminal opens a **new tab already `cd`'d there**. Great for jumping into a path
 a build tool just printed.
 </Aside>
 
+### Finding things
+
+`⌘F` opens a floating search overlay for the focused pane; `⌘⇧F` opens the same
+overlay across every pane in the session. Results appear as you type, with a
+preview of the lines around each hit.
+
+Where the text comes from depends on the pane:
+
+- **Agent panes** — the session **transcript**, not the terminal. This isn't a
+  shortcut, it's the only thing that works: Claude Code renders in the
+  alt-screen here (`tui = "fullscreen"`), and the alt-screen has no scrollback,
+  so searching the terminal grid would find only what's on screen this second.
+  The transcript is also simply better — it's the whole conversation, including
+  text inside collapsed tool output, and it isn't capped by
+  `scroll_buffer_size`. The pane → transcript join is the one the
+  [Links picker](/reference/keybindings/#terminal--zellij-hearth) already uses,
+  maintained by the Claude statusline.
+- **Every other pane** — its full scrollback.
+
+Inside the overlay: `⏎` jumps to the pane the hit came from, `^y` copies the
+matched line, `^s` flips between this-pane and every-pane (your query survives
+the switch), `Esc` closes.
+
+<Aside type="note" title="zellij's own search is still there">
+This doesn't replace `Ctrl g` → `s` (or `/`). Native search is the only thing
+that highlights matches **in place** and walks them with `n` / `p` inside the
+real pane, which is nicer for a shell you're already reading — it just can't see
+an alt-screen agent pane, which is why the overlay exists next to it rather than
+instead of it. Its exits now return you to **Locked**, not Normal.
+</Aside>
+
 ### Layouts
 
 zellij ships three swap layouts, cycled with `Alt <` / `Alt >`:

web/src/content/docs/reference/keybindings.md

@@ -68,7 +68,9 @@ cheatsheet always reflects the keys you actually have.
 | `Super ⇧P` | New pane, stay here (inherits cwd, no worktree hop) |
 | `Super T` | New tab at `$HOME` (born named `~`) |
 | `Super ⇧T` | New tab at the focused pane's directory (same worktree hop as `Super P`) |
-| `Super F` | Toggle the focused pane fullscreen (zoom to fill the tab, again to restore) |
+| `Super F` | **Find** — full-text search over the focused pane, live as you type |
+| `Super ⇧F` | The same overlay, opened across **every pane** in the session |
+| `Super ⏎` | Toggle the focused pane fullscreen (zoom to fill the tab, again to restore) |
 | `Super R` | Reload the terminal stack — quit/reopen Ghostty and restart zellij with the same tabs, panes and cwds; live Claude panes resume (also `zreload` from a shell) |
 | `Super Y` | yazi peek (floating previews; `Enter` on a dir opens a new tab there) |
 | `Super ⇧Y` | yazi jump (browse, then shell in that dir) |
@@ -79,6 +81,20 @@ cheatsheet always reflects the keys you actually have.
 | `Super ⇧C` | The same agent, **in place of** the focused pane instead of beside it — the replaced pane is suspended, not killed, and comes back when the agent quits |
 | `Ctrl ⌥⇧C` | Spawn a resident agent (this checkout) |
 
+**Find searches transcripts, not just scrollback.** In a shell pane the overlay
+searches the full scrollback. In an **agent pane** it searches that session's
+**transcript** instead — which is both necessary and better: Claude Code renders
+in the alt-screen here, and the alt-screen has no scrollback at all, so
+searching the terminal grid would only ever find what's currently on display.
+The transcript has the whole conversation, including text inside collapsed tool
+output. Inside the overlay: `⏎` jumps to the pane the hit came from, `^y` copies
+the matched line, `^s` switches between this-pane and every-pane without losing
+your query, `Esc` closes.
+
+zellij's own in-place search is still there and unchanged — `Ctrl g` to unlock,
+then `s` or `/` — for when you want matches highlighted in the real pane and
+`n`/`p` to walk them. It exits back to Locked rather than Normal.
+
 **Locked by default.** zellij boots in **Locked** input mode, so its single-key
 submode leaders (pane, tab, resize) stay inert until you press `Ctrl g` — a stray
 keystroke can't drop you into a submode. The `Super`-prefixed launchers above work
@@ -111,9 +127,10 @@ URL is hidden in the terminal escape sequence rather than shown on screen.
 ## Ghostty note
 
 Ghostty deliberately **unbinds** `⌘T`, `⌘P`, `⌘⇧P`, `⌘Y`, `⌘⇧Y`, `⌘⇧T`, `⌘F`,
-`⌘R`, `⌘C` and `⌘⇧C` so zellij owns them — the same keys work whether or not
-you're multiplexed. (`⌘⇧C` is unbound pre-emptively: Ghostty claims nothing there
-today, and the unbind keeps it that way if a future release does.)
+`⌘⇧F`, `⌘⏎`, `⌘R`, `⌘C` and `⌘⇧C` so zellij owns them — the same keys work
+whether or not you're multiplexed. (`⌘⇧C`, `⌘⇧F` and `⌘⏎` are unbound
+pre-emptively: Ghostty claims nothing there today, and the unbind keeps it that
+way if a future release does.)
 `Ctrl-Tab` is forwarded to zellij via the kitty keyboard protocol.
 
 `⌘D` and `⌘⇧D` are unbound too, but nothing takes them over: they do **nothing**.