docs: README, INSTALL.md (AI-guided setup)

2026-03-29 19:16:39 -04:00
parent e37b907326
commit f6a1cc4ebd
2 changed files with 410 additions and 0 deletions
@@ -0,0 +1,245 @@
+# Kitty-Workbench — AI-Guided Setup
+
+You are an AI assistant helping a user set up Kitty-Workbench. Follow these steps in order. Do not ask the user what they have — detect it yourself. Present options conversationally.
+
+## Step 0: Clone and Install
+
+If the repo is not already cloned locally, clone it:
+
+```bash
+git clone <repo-url>
+cd kitty-workbench
+```
+
+Install the package:
+
+```bash
+pip install .
+```
+
+If `pip install` fails due to PEP 668, use:
+
+```bash
+pip install --break-system-packages .
+```
+
+Verify it installed:
+
+```bash
+kitty-workbench --version
+```
+
+If already installed, skip to Step 1.
+
+## Step 1: Detect the Environment
+
+Run these commands and collect the output. Do NOT ask the user — just run them:
+
+```bash
+# Python
+python3 --version
+
+# Platform
+uname -s -r -m
+
+# Terminal environment
+echo "TERM_PROGRAM=$TERM_PROGRAM"
+echo "KITTY_PID=$KITTY_PID"
+echo "TMUX=$TMUX"
+echo "VTE_VERSION=$VTE_VERSION"
+
+# Available tools
+which kitty 2>/dev/null && echo "kitty: found" || echo "kitty: not found"
+which tmux 2>/dev/null && echo "tmux: found" || echo "tmux: not found"
+which chafa 2>/dev/null && echo "chafa: found" || echo "chafa: not found"
+which img2sixel 2>/dev/null && echo "img2sixel: found" || echo "img2sixel: not found"
+
+# Access topology — is the user local, SSH'd, or on remote desktop?
+echo "SSH_CONNECTION=$SSH_CONNECTION"
+echo "DISPLAY=$DISPLAY"
+echo "WAYLAND_DISPLAY=$WAYLAND_DISPLAY"
+who am i 2>/dev/null
+
+# Kitty remote control (only if kitty is installed)
+kitty @ ls 2>&1 | head -1 || true
+```
+
+## Step 2: Evaluate Options
+
+Based on what you detected, determine:
+
+### Access topology
+
+- **Native** (no `$SSH_CONNECTION`, has `$DISPLAY` or `$WAYLAND_DISPLAY`): All backends work.
+- **Remote desktop** (RDP/VNC session detected): All backends work — same as native.
+- **SSH** (`$SSH_CONNECTION` is set): Only **tmux** works reliably for pane splitting. Kitty splits won't work (`kitty @` can't reach the user's local kitty instance). The plain backend can't open windows on the user's local machine.
+
+### Available backends
+
+| Backend | Requirement | Check |
+|---------|------------|-------|
+| **kitty** | `$KITTY_PID` set, or `kitty` on PATH + `kitty @ ls` succeeds | Best image quality, native splits. Only works for native/remote-desktop users. |
+| **tmux** | `$TMUX` set, or `tmux` on PATH | Good image quality (sixel), works over SSH. Recommended default. |
+| **plain** | Always available | Opens TUI in a separate terminal window. No splits. |
+
+### Image protocol
+
+| Protocol | Check |
+|----------|-------|
+| **kitty graphics** | Only if using kitty backend |
+| **sixel** | `$TERM_PROGRAM` is one of: iTerm2, WezTerm, foot, contour, xterm, mlterm, mintty. Or `$VTE_VERSION` >= 7600 (GNOME Terminal 46+). Or `$TERM` contains "xterm-kitty". |
+| **ASCII art** | `chafa` on PATH. Always works as fallback. |
+| **none** | Plain text placeholder with file path. |
+
+## Step 3: Present Options
+
+Based on your evaluation, present the user's options conversationally. Be specific about what they have and what each option gives them.
+
+**If over SSH:**
+Tell the user tmux is their only practical option. If tmux is installed, recommend it. If not, recommend installing it (`apt install tmux` / `brew install tmux`). Mention that images will work if their local terminal supports sixel.
+
+**If native/remote desktop with tmux available:**
+Present tmux as the ready-now option. Optionally mention kitty as an upgrade for better image quality if they want to install it later.
+
+**If native/remote desktop in kitty:**
+Great — they get the best experience. Just need `allow_remote_control yes` in kitty.conf.
+
+**If no tmux and no kitty:**
+Recommend installing tmux (simplest) or kitty (best experience). Plain backend works but has no split panes.
+
+## Step 4: Execute Setup
+
+Based on what the user chose:
+
+1. **Create project directory:**
+   ```bash
+   mkdir -p ~/Kitty-Workbench
+   ```
+
+2. **If kitty backend chosen**, ensure remote control is enabled:
+   ```bash
+   # Check if already configured
+   grep -q "allow_remote_control" ~/.config/kitty/kitty.conf 2>/dev/null
+   ```
+   If not configured, add:
+   ```bash
+   mkdir -p ~/.config/kitty
+   echo "allow_remote_control yes" >> ~/.config/kitty/kitty.conf
+   ```
+
+3. **Optional: install chafa** for ASCII art image fallback:
+   - Linux: `sudo apt install chafa` or `sudo pacman -S chafa`
+   - macOS: `brew install chafa`
+
+## Step 5: Configure MCP
+
+Add the Kitty-Workbench MCP server to the user's AI CLI configuration.
+
+**Detect which CLI they're using** by checking for config files:
+
+```bash
+ls ~/.claude/settings.json 2>/dev/null && echo "Claude Code detected"
+ls ~/.gemini/settings.json 2>/dev/null && echo "Gemini CLI detected"
+ls ~/.config/gemini/settings.json 2>/dev/null && echo "Gemini CLI detected (alt path)"
+```
+
+**For Claude Code**, add to `~/.claude/settings.json` under `mcpServers`:
+```json
+{
+  "mcpServers": {
+    "kitty-workbench": {
+      "command": "kitty-workbench",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+**For Gemini CLI**, add to the appropriate MCP config.
+
+**For other/unknown CLIs**, print the MCP configuration JSON and tell the user to add it to their CLI's MCP settings. The server command is `kitty-workbench mcp` on stdio transport.
+
+## Step 6: Smoke Test
+
+Verify everything works:
+
+```bash
+# Check the CLI works
+kitty-workbench list
+
+# Check the project directory exists
+ls ~/Kitty-Workbench/
+```
+
+If the user is in tmux or kitty right now, you can also test the full flow:
+- Call `kitt_open` with a test project
+- Verify the TUI pane appears
+- Call `kitt_close` to clean up
+
+If not in the right terminal environment, skip the live test — it will work when they start a session later.
+
+## Step 7: Write START.md
+
+Write `~/Kitty-Workbench/START.md` — a personalized startup guide for this user's environment.
+
+Include:
+- Setup date
+- Detected backend and image protocol
+- Platform details
+- MCP configuration that was applied (which CLI, what config)
+- How to start a session (step by step for their specific setup)
+- What optional packages are installed
+- How to upgrade to a better backend later (if applicable)
+
+Example:
+
+```markdown
+# Kitty-Workbench — Start Guide
+
+**Setup date:** 2026-03-29
+**Backend:** tmux
+**Image protocol:** sixel
+**Platform:** Linux (Ubuntu 24.04)
+
+## Starting a Session
+
+1. Open a tmux session (or use an existing one)
+2. Start your AI CLI
+3. Tell the AI to open a Kitty-Workbench project — it will call `kitt_open` and the display pane appears as a tmux split
+
+## MCP Configuration
+
+Configured in `~/.claude/settings.json`:
+```json
+{
+  "mcpServers": {
+    "kitty-workbench": {
+      "command": "kitty-workbench",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+## Environment
+
+- Python: 3.11.4
+- Textual: 0.79.0
+- tmux: 3.4
+- sixel: supported (GNOME Terminal 46)
+- chafa: installed
+
+## Upgrading
+
+To switch to kitty backend later:
+1. Install kitty
+2. Add `allow_remote_control yes` to `~/.config/kitty/kitty.conf`
+3. Launch your AI CLI from within kitty
+4. Backend auto-detects — no config change needed
+```
+
+Adapt the content to match what you actually detected and configured. This file is for future AI sessions to read, so be precise.
+
+## Done
+
+Tell the user setup is complete and how to start their first session.