WIP: aesthetics!

README.md

@@ -20,18 +20,36 @@ That's it. No other config needed. See `:help turbo-debug` for customization.
 ## How It Works
 
 turbo-debug is **modal**. Press `<leader>dd` and you enter debug mode — the
-UI opens, keybindings activate, and you're debugging. Press `q` or
-`<leader>dd` again and everything disappears. Your editor is exactly as it
-was before.
+dap-ui layout opens, keybindings activate, virtual text lights up, and
+you're debugging. Press `<leader>dd` again (or `q`) and everything
+disappears: the session terminates, the UI closes, and every keybinding is
+restored to exactly what it was.
 
 This modal approach is inspired by
 [debugmaster.nvim](https://github.com/MironPascalCaseFan/debugmaster.nvim).
-During a debug session you need to **navigate** code and **inspect** state.
-You do not need to **edit**. So debug mode shadows editing keys (`c`, `d`,
-`s`, `r`, `x`) with debug actions and leaves all navigation keys untouched
-(`h`, `j`, `k`, `l`, `w`, `b`, `e`, `f`, `/`, `n`, etc.).
+During a debug session you **navigate** code and **inspect** state; you
+don't **edit**. So debug mode shadows editing keys (`c`, `d`, `s`, `r`,
+`x`) with debug actions and leaves all navigation keys untouched (`h`,
+`j`, `k`, `l`, `w`, `b`, `e`, `f`, `/`, `n`, etc.).
 
-When debug mode ends, every keybinding is restored to exactly what it was.
+### A nice text *and* GUI debugger
+
+The modal keymap is deliberately **left-hand optimized** so the right hand
+stays on the mouse for interacting with the dap-ui panes:
+
+- **Left hand on keyboard**: `c s d r C x X D W E q R` fire the twelve
+  rapid-use debug actions without leaving home row.
+- **Right hand on mouse**: click into Watches/Scopes/Stacks/Breakpoints
+  panes to expand trees, jump to frames, add watch expressions, or toggle
+  breakpoints from the GUI.
+
+Only two modal keys live on the right hand, both by universal convention:
+`K` for hover (matches the LSP hover key) and `?` for help.
+
+Inside dap-ui panes, the native dap-ui mappings still work — `d` removes a
+watch, `r` sends to REPL, `e` edits. The modal `d` (step-into) and `r`
+(step-out) yield to dap-ui in those buffers so you can manage the GUI
+without exiting debug mode.
 
 ## Keybindings
 
@@ -57,7 +75,34 @@ During debug mode, single-key controls:
 | `q` | Terminate session | `E` | Eval in REPL |
 | `R` | Restart session | `?` | Help popup |
 
-Press `?` during debug mode for a quick reference.
+Press `?` during debug mode for a quick reference that also lists dap-ui's
+native in-pane bindings (`<CR>`, `e`, `o`, `d`, `r`, `t`).
+
+### Extending keymaps
+
+Every key is user-overridable. Remap, disable, or add bindings via
+`setup()`:
+
+```lua
+require("turbo-debug").setup({
+  keys = {
+    step_over = "n",   -- remap a modal key
+    watch = false,     -- disable a modal key
+  },
+  global_keys = {
+    toggle = "<leader>D",   -- change the toggle chord
+  },
+  sidebar = "right",        -- "left" (default) or "right"
+  help_on_enter = false,    -- disable the help splash
+  quit_exits_mode = false,  -- q terminates but stays in debug mode
+})
+```
+
+### Statusline integration
+
+If you want a live debug indicator in your statusline, add
+`require("dap").status()` as a lualine/heirline component — it returns a
+progress message while debugging and an empty string when idle.
 
 ## Supported Languages