From f5dd2a6f58d815c8ca3ac3ab47a674f183ee4d86 Mon Sep 17 00:00:00 2001
From: Mortdecai <admin@mortdec.ai>
Date: Sun, 29 Mar 2026 20:26:12 -0400
Subject: [PATCH] fix: add tmux mouse setup to INSTALL.md, clarify
 Enter-to-submit on input widgets

---
 INSTALL.md                    | 17 ++++++++++++++++-
 src/kitty_workbench/server.py |  2 +-
 2 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/INSTALL.md b/INSTALL.md
index b497f9f..81e5dee 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -127,7 +127,22 @@ Based on what the user chose:
    echo "allow_remote_control yes" >> ~/.config/kitty/kitty.conf
    ```
 
-3. **Optional: install chafa** for ASCII art image fallback:
+3. **If tmux backend chosen**, enable mouse support so the user can click widgets in the TUI pane:
+   ```bash
+   # Check current setting
+   tmux show -g mouse 2>/dev/null
+   ```
+   If mouse is off or not set:
+   ```bash
+   tmux set -g mouse on
+   ```
+   To make it permanent, add to `~/.tmux.conf`:
+   ```bash
+   grep -q "set -g mouse on" ~/.tmux.conf 2>/dev/null || echo "set -g mouse on" >> ~/.tmux.conf
+   ```
+   Without this, tmux intercepts mouse clicks and the user cannot interact with checkboxes, buttons, or inputs in the display pane.
+
+4. **Optional: install chafa** for ASCII art image fallback:
    - Linux: `sudo apt install chafa` or `sudo pacman -S chafa`
    - macOS: `brew install chafa`
 
diff --git a/src/kitty_workbench/server.py b/src/kitty_workbench/server.py
index 319b34a..f0b1a23 100644
--- a/src/kitty_workbench/server.py
+++ b/src/kitty_workbench/server.py
@@ -217,7 +217,7 @@ def create_mcp_server(workbench_dir: Path = DEFAULT_WORKBENCH_DIR, socket_dir: s
     async def kitt_display(project: str, widget: str, content: str = "", items: str = "",
                            id: str = "", label: str = "", placeholder: str = "",
                            pane: str = "main", clear: bool = False) -> str:
-        """Push content to the display pane. Widget types: 'markdown' (rendered text), 'table' (columns+rows as JSON in content), 'checklist' (items as JSON array), 'button' (needs id+label), 'input' (needs id+placeholder). Use kitt_events to read user interactions."""
+        """Push content to the display pane. Widget types: 'markdown' (rendered text), 'table' (columns+rows as JSON in content), 'checklist' (items as JSON array), 'button' (needs id+label), 'input' (text field — needs id+placeholder, user must press Enter to submit). Tell the user to press Enter to submit text inputs. Use kitt_events to read user interactions."""
         return await srv.kitt_display(project, widget, content, items, id, label, placeholder, pane, clear)
 
     @mcp.tool()