docs: rewrite README with modal explanation, credits, screenshot placeholder

README.md

@@ -4,24 +4,46 @@ A zero-config debugging experience for Neovim 0.12+. One plugin install, full
 IDE-class debugging: inline variable values, hover inspection, persistent
 breakpoints, watch expressions, and modal keybindings that just work.
 
+Inspired by Turbo Pascal — the first IDE where you could just hit a key
+and start debugging.
+
+![turbo-debug screenshot](https://github.com/user-attachments/assets/TODO)
+
 ## Install
 
 ```lua
-vim.pack.add("swaits/turbo-debug.nvim")
+vim.pack.add("swaits/turbo-debug")
 ```
 
 That's it. No other config needed. See `:help turbo-debug` for customization.
 
-## Usage
+## How It Works
 
-Everything lives under `<leader>d` (with which-key support if installed):
+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.
 
-| Key | Action | Available |
+This modal approach is inspired by
-|-----|--------|-----------|
+[debugmaster.nvim](https://github.com/MironPascalCaseFan/debugmaster.nvim).
-| `<leader>dd` | Toggle debug mode | Always |
+During a debug session you need to **navigate** code and **inspect** state.
-| `<leader>dx` | Toggle breakpoint | Always |
+You do not need to **edit**. So debug mode shadows editing keys (`c`, `d`,
-| `<leader>dX` | Conditional breakpoint | Always |
+`s`, `r`, `x`) with debug actions and leaves all navigation keys untouched
-| `<leader>dD` | Clear all breakpoints | Always |
+(`h`, `j`, `k`, `l`, `w`, `b`, `e`, `f`, `/`, `n`, etc.).
+
+When debug mode ends, every keybinding is restored to exactly what it was.
+
+## Keybindings
+
+Everything lives under `<leader>d` (with
+[which-key](https://github.com/folke/which-key.nvim) support if installed):
+
+| Key | Action |
+|-----|--------|
+| `<leader>dd` | Toggle debug mode |
+| `<leader>dx` | Toggle breakpoint |
+| `<leader>dX` | Conditional breakpoint |
+| `<leader>dD` | Clear all breakpoints |
 
 During debug mode, single-key controls:
 
@@ -35,11 +57,13 @@ During debug mode, single-key controls:
 | `q` | Terminate session | `E` | Eval in REPL |
 | `R` | Restart session | `?` | Help popup |
 
-All navigation keys preserved. Modal keybindings vanish when you exit debug mode.
+Press `?` during debug mode for a quick reference.
 
 ## Supported Languages
 
-Adapter binaries must be installed (via mason, package manager, etc).
+turbo-debug ships adapter configs for 12 languages. You install the adapter
+binary (via [mason.nvim](https://github.com/williamboman/mason.nvim), your
+package manager, or manually) — turbo-debug handles all the configuration.
 
 | Language | Adapter | Language | Adapter |
 |----------|---------|----------|---------|
@@ -50,6 +74,36 @@ Adapter binaries must be installed (via mason, package manager, etc).
 | Rust | codelldb | Ruby | rdbg |
 | Swift | codelldb | Lua (Neovim) | osv |
 
+Rust gets special treatment: pressing `c` runs `cargo build` automatically
+and picks the binary via `vim.ui.select`.
+
+## What This Plugin Actually Does
+
+turbo-debug is **glue**. It does not implement a debugger, a UI framework,
+virtual text rendering, or breakpoint persistence. It configures and wires
+together these excellent plugins into a single cohesive experience:
+
+| Plugin | What it provides |
+|--------|-----------------|
+| [nvim-dap](https://github.com/mfussenegger/nvim-dap) | DAP client — the core debug engine |
+| [nvim-dap-ui](https://github.com/rcarriga/nvim-dap-ui) | Scopes, stacks, watches, REPL, console UI |
+| [nvim-nio](https://github.com/nvim-neotest/nvim-nio) | Async IO (required by nvim-dap-ui) |
+| [nvim-dap-virtual-text](https://github.com/theHamsta/nvim-dap-virtual-text) | Inline variable values in source code |
+| [persistent-breakpoints.nvim](https://github.com/Weissle/persistent-breakpoints.nvim) | Breakpoints that survive restarts |
+
+All five are loaded automatically via `vim.pack.add`. You never declare them.
+
+Adapter configurations are inlined from the work of these projects (no
+runtime dependency, we just studied their configs and wrote plain Lua tables):
+
+- [nvim-dap-python](https://github.com/mfussenegger/nvim-dap-python)
+- [nvim-dap-go](https://github.com/leoluz/nvim-dap-go)
+- [nvim-dap-vscode-js](https://github.com/mxsdev/nvim-dap-vscode-js)
+- [nvim-dap-lldb](https://github.com/julianolf/nvim-dap-lldb)
+- [nvim-dap-cs](https://github.com/NicholasMata/nvim-dap-cs)
+- [nvim-dap-ruby](https://github.com/suketa/nvim-dap-ruby)
+- [nvim-dap-kotlin](https://github.com/Mgenuit/nvim-dap-kotlin)
+
 ## License
 
 MIT

doc/turbo-debug.txt

@@ -36,7 +36,7 @@ Features:
 2. Installation                                 *turbo-debug-installation*
 
 Add one line to your init.lua: >lua
-  vim.pack.add("swaits/turbo-debug.nvim")
+  vim.pack.add("swaits/turbo-debug")
 <
 That's it. All dependencies are managed automatically.
 

turbo-debug-spec.md

@@ -14,7 +14,7 @@ and persistent-breakpoints into a single cohesive experience with modal
 keybindings. The user installs one plugin and gets everything.
 
 ```lua
-vim.pack.add("swaits/turbo-debug.nvim")
+vim.pack.add("swaits/turbo-debug")
 ```
 
 That's it. That's the whole setup.
@@ -132,7 +132,7 @@ C/C++/Rust only). Out of scope.
 
 ```lua
 -- init.lua
-vim.pack.add("swaits/turbo-debug.nvim")
+vim.pack.add("swaits/turbo-debug")
 ```
 
 One line. One plugin. Everything works.
@@ -582,7 +582,7 @@ Autocmd to close on any keypress. Content built from the keys table.
 
 A user who has never configured DAP should be able to:
 
-1. Add one line to their init.lua: `vim.pack.add("swaits/turbo-debug.nvim")`
+1. Add one line to their init.lua: `vim.pack.add("swaits/turbo-debug")`
 2. Open a file in any of the world's top 10 languages.
 3. Press `x` on a line to set a breakpoint (visible immediately in gutter).
 4. Press `<leader>d` to enter debug mode. See the help box. See the UI.