docs: document alternate-screen automation limits

3 files changed, 18 insertions, 0 deletions

diff --git a/docs/next/website/src/content/docs/agent-automation.mdx b/docs/next/website/src/content/docs/agent-automation.mdx
index 4e4e0f41..a07927ba 100644
--- a/docs/next/website/src/content/docs/agent-automation.mdx
+++ b/docs/next/website/src/content/docs/agent-automation.mdx
@@ -88,6 +88,12 @@ Pane input addresses the terminal regardless of its current occupant. Agent inpu
 
 At the CLI, both `pane read` and `agent read` print terminal text directly. The default is UTF-8 text with ANSI escapes stripped; use `--format ansi` or `--ansi` to preserve terminal escapes where the source exposes them. The `detection` source is always plain text. For every read source, `--lines N` returns the last N logical lines. The socket API returns the text at `.result.read.text`.
 
+## Known caveat: alternate-screen output
+
+Full-screen agents such as Claude Code and OpenCode may render in the terminal's alternate screen. Alternate-screen rows do not enter Herdr's host scrollback. If a response exceeds the visible pane, `recent` and `recent-unwrapped` cannot recover rows that the app no longer displays; increasing `--lines` does not make that history available. A larger font or smaller pane makes this more likely.
+
+Ask the agent for concise responses, enlarge the pane or use a smaller font, or use the agent's own transcript and scrolling controls. After scrolling inside the agent, use `--source visible` to read the page it currently renders.
+
 Successful `agent start`, `agent prompt`, and `agent wait` commands return the current agent at `.result.agent`. `pane wait-output` returns `.result.pane_id`, `.result.matched_line`, and the matched snapshot at `.result.read`.
 
 Wait commands have no default timeout and can wait indefinitely. On timeout or another server error, CLI commands print a JSON error to stderr and exit with status 1; invalid CLI syntax exits with status 2.
diff --git a/docs/next/website/src/content/docs/ja/agent-automation.mdx b/docs/next/website/src/content/docs/ja/agent-automation.mdx
index 78f949aa..44e20f53 100644
--- a/docs/next/website/src/content/docs/ja/agent-automation.mdx
+++ b/docs/next/website/src/content/docs/ja/agent-automation.mdx
@@ -88,6 +88,12 @@ herdr agent rename w1:p2 reviewer
 
 CLI では、`pane read` と `agent read` のどちらもターミナルテキストを直接出力します。デフォルトは ANSI エスケープを除去した UTF-8 テキストです。ソースに装飾が含まれる場合、`--format ansi` または `--ansi` でエスケープを残します。`detection` ソースは常にプレーンテキストです。すべての read ソースで、`--lines N` は末尾の N 論理行を返します。socket API ではテキストを `.result.read.text` に返します。
 
+## 既知の注意点: 代替画面の出力
+
+Claude Code や OpenCode などの全画面エージェントは、ターミナルの代替画面に描画することがあります。代替画面の行は Herdr のホスト側スクロールバックには入りません。応答が表示中のペインを超えると、アプリが表示しなくなった行を `recent` や `recent-unwrapped` で復元することはできません。`--lines` を増やしても、その履歴は取得できません。フォントが大きい場合やペインが小さい場合は、より起こりやすくなります。
+
+エージェントに簡潔な応答を求めるか、ペインを広げる、フォントを小さくする、またはエージェント自身のトランスクリプトやスクロール操作を使ってください。エージェント内でスクロールした後、`--source visible` を使うと、現在描画されているページを読み取れます。
+
 成功した `agent start`、`agent prompt`、`agent wait` は現在のエージェントを `.result.agent` に返します。`pane wait-output` は `.result.pane_id`、`.result.matched_line`、一致したスナップショット `.result.read` を返します。
 
 wait コマンドにはデフォルトのタイムアウトがなく、無期限に待機できます。タイムアウトやサーバーエラーでは JSON エラーを stderr に出して終了コード 1、CLI 構文エラーでは終了コード 2 を返します。
diff --git a/docs/next/website/src/content/docs/zh-cn/agent-automation.mdx b/docs/next/website/src/content/docs/zh-cn/agent-automation.mdx
index 18a81359..5fda8ca3 100644
--- a/docs/next/website/src/content/docs/zh-cn/agent-automation.mdx
+++ b/docs/next/website/src/content/docs/zh-cn/agent-automation.mdx
@@ -88,6 +88,12 @@ herdr agent rename w1:p2 reviewer
 
 在 CLI 中,`pane read` 和 `agent read` 都直接打印终端文本。默认输出去除 ANSI 转义的 UTF-8 文本;来源包含样式时,使用 `--format ansi` 或 `--ansi` 保留终端转义。`detection` 来源始终是纯文本。对所有 read 来源,`--lines N` 都返回末尾 N 个逻辑行。socket API 在 `.result.read.text` 返回文本。
 
+## 已知注意事项:备用屏幕输出
+
+Claude Code 和 OpenCode 等全屏智能体可能会在终端的备用屏幕中绘制。备用屏幕中的行不会进入 Herdr 的主机回滚缓冲区。如果回复超出可见窗格,`recent` 和 `recent-unwrapped` 无法恢复应用已不再显示的行;增大 `--lines` 也无法获取这些历史内容。字体较大或窗格较小时更容易遇到此限制。
+
+可以要求智能体简洁回复、扩大窗格或使用较小字体,也可以使用智能体自身的记录和滚动控件。在智能体内部滚动后,使用 `--source visible` 读取它当前绘制的页面。
+
 成功的 `agent start`、`agent prompt` 和 `agent wait` 会在 `.result.agent` 返回当前智能体。`pane wait-output` 返回 `.result.pane_id`、`.result.matched_line` 以及位于 `.result.read` 的匹配快照。
 
 等待命令没有默认超时,可能无限等待。超时或服务器错误会把 JSON 错误写到 stderr 并以状态 1 退出;CLI 语法错误以状态 2 退出。