From e112d2a9176b51927bbc0f862a19d196f94af7a7 Mon Sep 17 00:00:00 2001
From: Mario Zechner <badlogicgames@gmail.com>
Date: Sun, 25 Jan 2026 21:34:07 +0100
Subject: [PATCH] docs(coding-agent): move terminal setup to
 docs/terminal-setup.md

---
 packages/coding-agent/README.md              | 48 +--------------
 packages/coding-agent/docs/terminal-setup.md | 65 ++++++++++++++++++++
 2 files changed, 66 insertions(+), 47 deletions(-)
 create mode 100644 packages/coding-agent/docs/terminal-setup.md

diff --git a/packages/coding-agent/README.md b/packages/coding-agent/README.md
index 2352c313..31c2fe81 100644
--- a/packages/coding-agent/README.md
+++ b/packages/coding-agent/README.md
@@ -101,53 +101,7 @@ Adjust the path (`~/.zshrc`, `~/.bashrc`, etc.) to match your shell config.
 
 ### Terminal Setup
 
-Pi uses the [Kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/) for reliable modifier key detection. Most modern terminals support this protocol, but some require configuration.
-
-**Kitty, iTerm2:** Work out of the box.
-
-**Ghostty:** Add to your Ghostty config (`~/.config/ghostty/config`):
-
-```
-keybind = alt+backspace=text:\x1b\x7f
-keybind = shift+enter=text:\n
-```
-
-**wezterm:** Create `~/.wezterm.lua`:
-
-```lua
-local wezterm = require 'wezterm'
-local config = wezterm.config_builder()
-config.enable_kitty_keyboard = true
-return config
-```
-
-**VS Code (Integrated Terminal):** Add to `keybindings.json` to enable `Shift+Enter` for multi-line input:
-
-```json
-{
-  "key": "shift+enter",
-  "command": "workbench.action.terminal.sendSequence",
-  "args": { "text": "\u001b[13;2u" },
-  "when": "terminalFocus"
-}
-```
-
-**Windows Terminal:** Add to `settings.json` (Ctrl+Shift+, or Settings → Open JSON file):
-
-```json
-{
-  "actions": [
-    {
-      "command": { "action": "sendInput", "input": "\u001b[13;2u" },
-      "keys": "shift+enter"
-    }
-  ]
-}
-```
-
-If you already have an `actions` array, add the object to it.
-
-**IntelliJ IDEA (Integrated Terminal):** The built-in terminal has limited escape sequence support. Note that Shift+Enter cannot be distinguished from Enter in IntelliJ's terminal. If you want the hardware cursor visible, set `PI_HARDWARE_CURSOR=1` before running pi (disabled by default for compatibility). Consider using a dedicated terminal emulator for the best experience.
+Pi uses the [Kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/) for reliable modifier key detection. Kitty and iTerm2 work out of the box. Other terminals may need configuration. See [docs/terminal-setup.md](docs/terminal-setup.md).
 
 ### API Keys & OAuth
 
diff --git a/packages/coding-agent/docs/terminal-setup.md b/packages/coding-agent/docs/terminal-setup.md
new file mode 100644
index 00000000..9d333fba
--- /dev/null
+++ b/packages/coding-agent/docs/terminal-setup.md
@@ -0,0 +1,65 @@
+# Terminal Setup
+
+Pi uses the [Kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/) for reliable modifier key detection. Most modern terminals support this protocol, but some require configuration.
+
+## Kitty, iTerm2
+
+Work out of the box.
+
+## Ghostty
+
+Add to your Ghostty config (`~/.config/ghostty/config`):
+
+```
+keybind = alt+backspace=text:\x1b\x7f
+keybind = shift+enter=text:\n
+```
+
+## WezTerm
+
+Create `~/.wezterm.lua`:
+
+```lua
+local wezterm = require 'wezterm'
+local config = wezterm.config_builder()
+config.enable_kitty_keyboard = true
+return config
+```
+
+## VS Code (Integrated Terminal)
+
+Add to `keybindings.json` to enable `Shift+Enter` for multi-line input:
+
+```json
+{
+  "key": "shift+enter",
+  "command": "workbench.action.terminal.sendSequence",
+  "args": { "text": "\u001b[13;2u" },
+  "when": "terminalFocus"
+}
+```
+
+## Windows Terminal
+
+Add to `settings.json` (Ctrl+Shift+, or Settings → Open JSON file):
+
+```json
+{
+  "actions": [
+    {
+      "command": { "action": "sendInput", "input": "\u001b[13;2u" },
+      "keys": "shift+enter"
+    }
+  ]
+}
+```
+
+If you already have an `actions` array, add the object to it.
+
+## IntelliJ IDEA (Integrated Terminal)
+
+The built-in terminal has limited escape sequence support. Shift+Enter cannot be distinguished from Enter in IntelliJ's terminal.
+
+If you want the hardware cursor visible, set `PI_HARDWARE_CURSOR=1` before running pi (disabled by default for compatibility).
+
+Consider using a dedicated terminal emulator for the best experience.