From 2e2cdfa242da22fe53b289139ca8ce2006c716bd Mon Sep 17 00:00:00 2001
From: l0ng-ai <24760907+l0ng-ai@users.noreply.github.com>
Date: Sun, 16 Aug 2026 08:51:18 +0800
Subject: [PATCH] docs(cli): say that capture answers with the alternate screen
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A pane running an editor or a pager answers `capture` with that
program's screen, and the scrollback behind it is not in the reply.
Measured: with a pane on the alternate screen the capture holds the
alt-screen marker and not the main-screen one; after leaving it, the
main scrollback is back and the alt content is gone, with only the
echoed command left behind — which was typed on the main screen and
belongs there.

That is right, and it is the sort of right that reads as a bug from the
outside. An agent that captures a pane mid-`less` gets a screenful and
no history, and the obvious conclusion — output was lost — is wrong. So
the help says which of the two you are holding, and that an
empty-looking capture is usually a TUI in front of the scrollback.

Also noted there: long output is trimmed from the oldest end, so a
capture after a big build gives the end of it. `seq 1 200000` through a
pane comes back as the last ~70 KB, ending at the prompt.

Checked while here, and correct: `send` carries an 8000-character
payload with nothing truncated.
---
 crates/tty7-cli/src/cli.rs | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/crates/tty7-cli/src/cli.rs b/crates/tty7-cli/src/cli.rs
index d517fc48..27de76a6 100644
--- a/crates/tty7-cli/src/cli.rs
+++ b/crates/tty7-cli/src/cli.rs
@@ -97,7 +97,20 @@ pub enum Command {
     #[command(
         about = "Print a pane's output — as text with `--plain`, otherwise with its ANSI \
                  escapes intact, decoded as UTF-8 (invalid bytes become U+FFFD): the \
-                 newest scrollback segment by default"
+                 newest scrollback segment by default",
+        long_about = "Print a pane's output — as text with `--plain`, otherwise with its \
+                      ANSI escapes intact, decoded as UTF-8 (invalid bytes become \
+                      U+FFFD): the newest scrollback segment by default.\n\n\
+                      What comes back depends on what the pane is showing. A pane running \
+                      a full-screen program — an editor, a pager, anything on the \
+                      alternate screen — answers with that program's screen, and the \
+                      scrollback behind it is not in the reply. Once the program exits \
+                      the scrollback is there again, with the alternate screen gone. So \
+                      an empty-looking capture from a pane that has produced plenty is \
+                      usually a TUI sitting in front of it, not lost output.\n\n\
+                      Long output is trimmed from the oldest end, so a capture after a \
+                      big build gives you the end of it — which is the part worth \
+                      reading."
     )]
     Capture(CaptureArgs),