fix: add Alt+V as clipboard image paste shortcut on macOS and document it (#852) (#854)

docs/commands.md

@@ -74,9 +74,12 @@ See [Parallel Orchestration](./parallel-orchestration.md) for full documentation
 | `Ctrl+Alt+G` | Toggle dashboard overlay |
 | `Ctrl+Alt+V` | Toggle voice transcription |
 | `Ctrl+Alt+B` | Show background shell processes |
+| `Ctrl+V` / `Alt+V` | Paste image from clipboard (screenshot → vision input) |
 | `Escape` | Pause auto mode (preserves conversation) |
 
 > **Note:** In terminals without Kitty keyboard protocol support (macOS Terminal.app, JetBrains IDEs), slash-command fallbacks are shown instead of `Ctrl+Alt` shortcuts.
+>
+> **Tip:** If `Ctrl+V` is intercepted by your terminal (e.g. Warp), use `Alt+V` instead for clipboard image paste.
 
 ## CLI Flags
 

packages/pi-coding-agent/src/core/keybindings.ts

@@ -65,7 +65,7 @@ export const DEFAULT_APP_KEYBINDINGS: Record<AppAction, KeyId | KeyId[]> = {
 	externalEditor: "ctrl+g",
 	followUp: "alt+enter",
 	dequeue: "alt+up",
-	pasteImage: process.platform === "win32" ? "alt+v" : "ctrl+v",
+	pasteImage: process.platform === "win32" ? "alt+v" : ["ctrl+v", "alt+v"],
 	newSession: [],
 	tree: [],
 	fork: [],