From 49772db38634bda1721afeac8610ec3106dd16af Mon Sep 17 00:00:00 2001
From: amandeavor <>
Date: Fri, 25 Sep 2026 07:43:00 +0000
Subject: [PATCH] docs(tui): document Vim mode keys in README

Add a Vim mode section to packages/tui/README.md listing the normal-mode
bindings implemented in vim-mode.ts so users do not have to read the source.

Closes #426
---
 packages/tui/README.md | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/packages/tui/README.md b/packages/tui/README.md
index 7483af28..2d8b3cad 100644
--- a/packages/tui/README.md
+++ b/packages/tui/README.md
@@ -109,6 +109,25 @@ Shift plus Enter and Ctrl plus Enter depend on the terminal reporting a modified
 
 Ctrl plus Backspace also depends on a distinct terminal sequence. When a terminal sends the ordinary Backspace byte for both keys, use Alt plus Backspace or Ctrl plus W for word deletion. Ordinary Backspace always remains single-grapheme deletion.
 
+## Vim mode
+
+Toggle with `/vim`. Editing starts in insert mode. Escape switches to normal mode; Escape in normal mode clears a pending `d` or `f` prefix.
+
+| Action | Keys |
+| --- | --- |
+| Move left / down / up / right | `h` `j` `k` `l`, arrow keys |
+| Word forward / back | `w` `b`, or the terminal word-left / word-right keys |
+| Line start / end | `0` `$`, Home, End |
+| Find next character on the line | `f` then a character |
+| Enter insert mode | `i` (here), `a` (after cursor), `I` (line start), `A` (line end), `o` (open below), `O` (open above) |
+| Delete character under cursor | `x` |
+| Delete current line / word forward | `dd` / `dw` |
+| Undo / redo | `u` / Ctrl+R |
+| Paste from the kill ring | `p` or `P` |
+| Open a slash command | `/` or `:` (both insert `/` and return to insert mode) |
+
+Enter, Alt+Enter follow-up, and Tab stay with the ordinary editor bindings in normal mode.
+
 ## Quit and detach
 
 `/detach` releases this attachment without cancelling work. `/quit` uses the host-injected SDK lifecycle surface to interrupt work and shut down the daemon after durable cleanup. Shared sessions or clients require confirmation. Escape interrupts while staying attached. Ctrl+C clears the editor; a second press within 500 ms quits. Ctrl+D quits with an empty editor. A missing host-control surface produces an explicit error, not a detach fallback. Failed or stalled graceful cleanup offers a separate force confirmation when the host supports it.