docs: explain modified-arrow shell bindings

refs #1370

3 files changed, 60 insertions, 0 deletions

diff --git a/docs/next/website/src/content/docs/ja/troubleshooting.mdx b/docs/next/website/src/content/docs/ja/troubleshooting.mdx
index c1eca500..3b857512 100644
--- a/docs/next/website/src/content/docs/ja/troubleshooting.mdx
+++ b/docs/next/website/src/content/docs/ja/troubleshooting.mdx
@@ -26,6 +26,26 @@ OS、外側のターミナル名とバージョン、ローカルまたはリモ
 
 長期サポート版 Linux ディストリビューションの古いターミナルパッケージで特に発生します。確認済みの境界キャプチャと上流参照は [Herdr issue #1116](https://github.com/ogulcancelik/herdr/issues/1116) を参照してください。現在のターミナルでも発生する場合は、正確なバージョンと Herdr の外でも発生するかを報告してください。
 
+## Option+Left または Option+Right を押すと `;3D` または `;3C` が入力される
+
+ターミナルは一般に、Alt+Left と Alt+Right を標準の修飾付き矢印シーケンス `ESC[1;3D` と `ESC[1;3C` として送信します。macOS では、まず外側のターミナルで Option を Alt として扱うよう設定する必要があります。シェルがこれらのシーケンスを割り当てていない場合、zsh は残りの文字を `;3D` または `;3C` と表示することがあります。これは kitty、Alacritty、その他のターミナルで発生する可能性があります。Herdr と tmux はどちらも元の修飾付き矢印入力を保持します。
+
+すべてのターミナルとネストしたシェルで修飾付き矢印を単語移動として使う場合は、zsh のバインドを明示的に追加します:
+
+```zsh
+bindkey $'\e[1;3D' backward-word
+bindkey $'\e[1;3C' forward-word
+```
+
+kitty の外では動作するのに Herdr 内では動作しないことがあります。これは kitty の自動 zsh インテグレーションが、kitty が直接起動したシェルにだけこれらのバインドを追加し、ターミナルマルチプレクサーが起動したシェルには追加しないためです。kitty の[手動シェルインテグレーション手順](https://sw.kovidgoyal.net/kitty/shell-integration/#manual-shell-integration)に従うか、シェルへ届く前に `kitty.conf` でキーを割り当ててください:
+
+```text
+map alt+left send_text all \x1bb
+map alt+right send_text all \x1bf
+```
+
+ターミナルアプリケーションが Alt+Left と Alt+Right を直接使用する場合があるため、Herdr は修飾付き矢印を意図的に書き換えません。調査の詳細は [Herdr issue #1370](https://github.com/ogulcancelik/herdr/issues/1370) を参照してください。
+
 ## Herdr を更新したのに実行中のセッションが古い
 
 バイナリを更新しても、互換性のある実行中サーバーは自動で置き換わらないことがあります。`herdr status` を確認してください。更新済みサーバーを起動するには、セッションを停止して Herdr を再起動します:
diff --git a/docs/next/website/src/content/docs/troubleshooting.mdx b/docs/next/website/src/content/docs/troubleshooting.mdx
index 34afb94d..bbbf5db4 100644
--- a/docs/next/website/src/content/docs/troubleshooting.mdx
+++ b/docs/next/website/src/content/docs/troubleshooting.mdx
@@ -26,6 +26,26 @@ Update the outer terminal to a version containing its upstream fix:
 
 This is especially common with older terminal packages from long-term-support Linux distributions. See [Herdr issue #1116](https://github.com/ogulcancelik/herdr/issues/1116) for the confirmed boundary captures and upstream references. If the problem remains on a current terminal version, report the exact terminal version and whether it also happens outside Herdr.
 
+## Option+Left or Option+Right inserts `;3D` or `;3C`
+
+Terminals commonly send Alt+Left and Alt+Right as the standard modified-arrow sequences `ESC[1;3D` and `ESC[1;3C`. On macOS, the outer terminal must first be configured to treat Option as Alt. If the shell does not bind these sequences, zsh may display their remaining characters as `;3D` or `;3C`. This can happen with kitty, Alacritty, and other terminals; Herdr and tmux both preserve the original modified-arrow input.
+
+Add explicit zsh bindings if you want modified arrows to perform word navigation in every terminal and nested shell:
+
+```zsh
+bindkey $'\e[1;3D' backward-word
+bindkey $'\e[1;3C' forward-word
+```
+
+Kitty can appear to work differently outside Herdr because its automatic zsh integration adds these bindings only to shells started directly by kitty, not shells created by terminal multiplexers. Follow kitty's [manual shell integration instructions](https://sw.kovidgoyal.net/kitty/shell-integration/#manual-shell-integration), or map the keys in `kitty.conf` before they reach the shell:
+
+```text
+map alt+left send_text all \x1bb
+map alt+right send_text all \x1bf
+```
+
+Herdr deliberately does not rewrite modified arrows because terminal applications may use Alt+Left and Alt+Right directly. See [Herdr issue #1370](https://github.com/ogulcancelik/herdr/issues/1370) for the investigation.
+
 ## Herdr updated, but the running session is still old
 
 Updating the binary does not always replace a compatible server that is already running. Check `herdr status`. To start the updated server, stop the session and launch Herdr again:
diff --git a/docs/next/website/src/content/docs/zh-cn/troubleshooting.mdx b/docs/next/website/src/content/docs/zh-cn/troubleshooting.mdx
index 4a5ec6da..39d23f75 100644
--- a/docs/next/website/src/content/docs/zh-cn/troubleshooting.mdx
+++ b/docs/next/website/src/content/docs/zh-cn/troubleshooting.mdx
@@ -26,6 +26,26 @@ herdr status
 
 长期支持版 Linux 发行版中的旧终端软件包尤其容易出现此问题。已确认的边界捕获和上游链接见 [Herdr issue #1116](https://github.com/ogulcancelik/herdr/issues/1116)。如果当前版本仍有问题，请报告准确的终端版本，以及该问题是否也会在 Herdr 外出现。
 
+## 按 Option+Left 或 Option+Right 时输入 `;3D` 或 `;3C`
+
+终端通常把 Alt+Left 和 Alt+Right 发送为标准的带修饰键方向键序列 `ESC[1;3D` 和 `ESC[1;3C`。在 macOS 上，需要先把外层终端配置为将 Option 视为 Alt。如果 shell 没有绑定这些序列，zsh 可能会把剩余字符显示为 `;3D` 或 `;3C`。kitty、Alacritty 和其他终端都可能出现这种情况；Herdr 和 tmux 都会保留原始的带修饰键方向键输入。
+
+如果希望带修饰键的方向键在所有终端和嵌套 shell 中都执行按单词移动，请添加明确的 zsh 绑定:
+
+```zsh
+bindkey $'\e[1;3D' backward-word
+bindkey $'\e[1;3C' forward-word
+```
+
+kitty 在 Herdr 外可能表现不同，因为它的自动 zsh 集成只会为 kitty 直接启动的 shell 添加这些绑定，而不会为终端多路复用器创建的 shell 添加。请按照 kitty 的[手动 shell 集成说明](https://sw.kovidgoyal.net/kitty/shell-integration/#manual-shell-integration)，或在按键到达 shell 前通过 `kitty.conf` 映射它们:
+
+```text
+map alt+left send_text all \x1bb
+map alt+right send_text all \x1bf
+```
+
+终端应用可能会直接使用 Alt+Left 和 Alt+Right，因此 Herdr 不会改写带修饰键的方向键。调查详情见 [Herdr issue #1370](https://github.com/ogulcancelik/herdr/issues/1370)。
+
 ## Herdr 已更新，但运行中的会话仍是旧版本
 
 更新二进制文件不一定会替换已经运行且兼容的服务器。先检查 `herdr status`。要启动更新后的服务器，请停止会话并重新启动 Herdr: