docs: finalize next release documentation

1 files changed, 20 insertions, 0 deletions

diff --git a/website/src/content/docs/troubleshooting.mdx b/website/src/content/docs/troubleshooting.mdx
index 34afb94d..bbbf5db4 100644
--- a/website/src/content/docs/troubleshooting.mdx
+++ b/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: