textual-debugger 0.2.12__tar.gz → 0.2.14__tar.gz

{textual_debugger-0.2.12 → textual_debugger-0.2.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: textual-debugger
-Version: 0.2.12
+Version: 0.2.14
 Summary: A TUI debugger for Python, Perl, and other languages.  Based on textual.
 Author-email: Al Danial <al.danial@gmail.com>
 License: textual-debugger is licensed to you under the MIT/X Consortium license:
@@ -54,6 +54,8 @@ Requires-Dist: pygments>=2.17.0
 Requires-Dist: fastapi>=0.115.0
 Requires-Dist: uvicorn>=0.30.0
 Requires-Dist: mcp<3.0.0,>=2.0.0
+Provides-Extra: edit
+Requires-Dist: textual[syntax]>=8.0.0; extra == "edit"
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
@@ -123,7 +125,11 @@ automated, headless debugging workflows and AI-assisted debugging
 built with `textual`, `prompt-toolkit`, `urwid`, `curses`, `rich`, and so on
 
 - comes with a post-mortem exception hook that can be installed in Python programs
-to have `tdb` pop open automatically at the first uncaught exception
+to have `tdb` pop open automatically at the first uncaught exception, and a live
+breakpoint hook (`tdb.breakpoint()` in Python, `Devel::TdbRemote::breakpoint()`
+in Perl, `Tdb.breakpoint` in Ruby, `tdb.Breakpoint()` in Go, `tdb_breakpoint()`
+in C/C++, `tdb::breakpoint()` in Rust, `Tdb.breakpoint ()` in OCaml) that opens
+`tdb` paused at a line of your choosing
 
 - can be entirely keyboard-driven
 making it suitable for operation in non-graphical environments (mouse support is
@@ -168,11 +174,13 @@ uvx --from textual-debugger tdb  my_program.py
 # show comprehensive documentation in a terminal-based Markdown viewer
 tdb --doc
 
-# show where tdb is installed, where its bundled Perl PadWalker module
-# lives, and the Help > About text
+# show the Help > About text, where tdb and its config, breakpoints and
+# log files live, and the path + version of each interpreter and native
+# debugger it would use (python, gdb, lldb-dap, perl, ruby, dlv,
+# ocamlearlybird, bash, tcsh, pwsh)
 tdb --info
 
-# debug a script (stops at first line by default)
+# debug a Python program (stops at first line by default)
 tdb my_program.py
 
 # debug with arguments
@@ -207,7 +215,7 @@ tdb --python /path/to/venv/bin/python my_program.py
 # step into, or stop at tracebacks in library code
 tdb --no-just-my-code --python /path/to/venv/bin/python my_program.py
 
-# run until first breakpoint or exit
+# run until first breakpoint (persisted during a prior run) or exit
 tdb --no-stop-on-entry my_program.py
 
 # run the debuggee in an external terminal
@@ -232,7 +240,7 @@ tdb -r remotehost:5678 --local-root /my/code/dir --remote-root /app -k my_progra
 # attach, which can leave it suspended after tdb quits
 tdb -r remotehost:5678 --no-pause-on-attach
 
-# separate tdb arguments from debuggee arguments with `--` 
+# separate tdb arguments from debuggee arguments with `--`
 tdb --python /path/to/venv/bin/python -- my_program.py -k 17 --max 23.3
 ```
 
@@ -250,7 +258,7 @@ languages are supported out of the box:
 | Language | Adapter(s) | Dependencies           | Feature level |
 |----------|------------|------------------------|---------------|
 | Python | `debugpy` (default) | Python ≥ 3.11 | everything in this README |
-| C / C++ (any native binary) | `gdb` (default), `lldb-dap` (alternate) | `gdb -i dap` requires GDB ≥ 14; `lldb-dap` ships with LLVM ≥ 17 (e.g. `apt install lldb`) | core debugging: breakpoints, stepping, stack, variables, evaluate console + remote attach (gdbserver/lldb-server, local symbol-bearing executable required) |
+| C / C++ (any native binary) | `gdb` (default), `lldb-dap` (alternate) | `gdb -i dap` requires GDB ≥ 14 built with Python (RHEL 8/9: `dnf install gcc-toolset-14-gdb`, see [C/C++ tips](#cc-tips)); `lldb-dap` ships with LLVM ≥ 17 (e.g. `apt install lldb`) | core debugging: breakpoints, stepping, stack, variables, evaluate console + remote attach (gdbserver/lldb-server, local symbol-bearing executable required) |
 | Rust (explicit `--lang rust`) | `gdb` (Linux default), `lldb-dap` (macOS default) | any rustc building with debug info; GDB ≥ 14 or LLVM `lldb-dap` ≥ 17 (concurrency ownership evidence additionally requires stable Rust 1.98) | core debugging + best-effort Rust concurrency inspection + remote attach |
 | Perl | perl-tdb (bundled) | perl ≥ 5.18 on PATH  | core debugging + remote attach |
 | Bash | bash-tdb (bundled) | bash ≥ 4.4 on PATH  | core debugging (no remote attach) |
@@ -297,6 +305,23 @@ The language is auto-detected from the debug target:
 it (`tdb --lang cpp --adapter lldb-dap ./myprog`). Rust always requires the
 explicit language selection (`tdb --lang rust target/debug/app`).
 
+`--adapter` also accepts a full path to a `gdb`, `lldb-dap`, or `dlv`
+executable (`tdb --adapter /opt/llvm/bin/lldb-dap ./myprog`,
+`tdb --adapter /usr/bin/gdb-multiarch ./myprog`,
+`tdb --adapter ~/go/bin/dlv ./main.go`). The adapter id is taken from the
+file's basename — versioned and variant names such as `lldb-dap-21` and
+`gdb-multiarch` work — and that exact executable is used for the session,
+ahead of anything on `$PATH` or in `config.json`'s `adapters` map.
+`tdb --info` shows which `gdb` and `lldb-dap` would be used otherwise.
+
+`gdb`'s DAP mode needs GDB ≥ 14, so `tdb` checks `gdb --version` before
+starting a session. A `gdb` that is provably too old is refused with a
+message naming its path and version; when that `gdb` came from `PATH`
+(not from `--adapter` or `config.json`), `tdb` first looks for a newer one
+installed by Red Hat's Software Collections
+(`/opt/rh/gcc-toolset-*/root/usr/bin/gdb`, `/opt/rh/devtoolset-*/...`) and
+uses the newest that qualifies. See [C/C++ tips](#cc-tips) for RHEL 8.
+
 > **Migration note:** extensionless Python scripts without a `python` shebang
 > were previously assumed to be Python; they now require `--lang python`.
 
@@ -341,7 +366,10 @@ language — Python, Perl, Bash, Tcsh, Ruby, and C/C++, OCaml native, or Rust
 sessions via `--adapter lldb-dap` — see
 [External Terminal Support](#external-terminal-support). Go and PowerShell do
 not support `--terminal` yet (`dlv dap` and PSES have no terminal-routing
-mode).
+mode). Typing into the Console view to feed the program's stdin works for
+Python, Perl, Bash, Tcsh, Ruby, and PowerShell, but not for C/C++, Rust,
+OCaml, or Go, whose adapters spawn the debuggee themselves — see
+[Console Output and Input](#console-output-and-input).
 
 **Bash limitations (v1):** the bash adapter uses bash's own `DEBUG` trap and
 has a smaller feature set than Python:
@@ -407,10 +435,16 @@ picture:
   backtrace instead.
 - No Windows support, no remote attach, and a stripped native binary that
   byte-checking can't identify needs `--lang ocaml`.
+- No stdin forwarding from the Console view (both adapters spawn the
+  program themselves); a program that reads stdin needs `--terminal`
+  (native, `--adapter lldb-dap`) or input from a file.
 
 **Go limitations (v1):**
 
 - `--terminal` is not supported (`dlv dap` has no terminal-routing mode).
+- No stdin forwarding from the Console view: `dlv dap` spawns the program
+  itself, so a program that reads stdin must get it from a file or pipe on
+  its command line.
 - The Goroutines workspace's wait graph shows channel-send/-receive,
   mutex, and `WaitGroup` edges; a goroutine parked in a `select` is
   classified but contributes no wait edge (Delve can't tell which of the
@@ -437,9 +471,17 @@ See [Go](#go) below for launch details.
   If no breakpoint in a file can be
   bound, `tdb` prints a console warning suggesting the program may lack
   debug info.
+- The Console view's stdin line is not available: `gdb -i dap` and
+  `lldb-dap` spawn the program themselves, so `tdb` has no handle on its
+  stdin. A program that reads stdin needs `--terminal` (with
+  `--adapter lldb-dap`) or its input from a file.
 - Stack frames pointing into system libraries often have no source on disk;
   the Code View shows a `<Could not read …>` placeholder while the stack,
   variables, and evaluate console remain fully usable.
+- For compiled executables, the Code View shows shows a brief note while
+  it attempts to load the associated source file.  The note will identify
+  the failure reason if the source cannot be loaded (executable was built
+  without `-g`, or the adapter is not working, e.g. a GDB too old for DAP).
 - GDB (the default adapter) has the most complete libstdc++
   pretty-printing. `lldb-dap` (via `--adapter lldb-dap`) also debugs
   GCC-built binaries fine.  DWARF is compiler-neutral.
@@ -450,6 +492,80 @@ See [Go](#go) below for launch details.
 - `--terminal` (see [External Terminal Support](#external-terminal-support))
   requires `--adapter lldb-dap`; GDB's DAP mode has no terminal integration
   and `tdb` refuses `--terminal` with the default `gdb` adapter.
+- **GDB source-location quirk:** some GDB builds (RHEL 8 among them)
+  report no source file for a stopped frame -- `info source` answers
+  "No current source file" -- until a `list` command has selected the
+  default source file. `tdb` therefore sends `list` once, before its
+  first stack query, so the Code View can find the source. This is why a
+  fresh gdb session shows `Current source file is …` in `info source`
+  from the evaluate console without you having typed `list`.
+- **RHEL 8 (and 9) gdb is too old for DAP:** the stock `/usr/bin/gdb` is
+  8.2 on RHEL 8 (10.2 on RHEL 9) and answers `gdb -i dap` with
+  ``Interpreter `dap' unrecognized``. Install a newer one from the
+  GCC Toolset, which leaves `/usr/bin/gdb` alone:
+
+  ```bash
+  sudo dnf install gcc-toolset-14-gdb   # gdb 14.2 under /opt/rh/gcc-toolset-14
+  ```
+
+  `tdb` then finds `/opt/rh/gcc-toolset-14/root/usr/bin/gdb` by itself
+  whenever the `gdb` on `PATH` is missing or too old — no `scl enable`
+  needed (`tdb --info` shows it as `gdb used instead`). Two things pin
+  the old one and must be changed by hand: `--adapter /usr/bin/gdb`, and
+  an `"adapters": {"gdb": "/usr/bin/gdb"}` entry in `config.json` (`tdb`
+  seeds that entry with whatever `gdb` was on `PATH` the first time it
+  wrote the file). Either delete the entry or point it at the toolset
+  gdb. A GDB ≥ 14 that was built without Python support gives the same
+  ``Interpreter `dap' unrecognized`` error (`gdb --configuration` shows
+  `--without-python`); use `--adapter lldb-dap` or a gdb built with
+  Python.
+
+**Attach to a running process:** `tdb -a PID` attaches gdb (or `--adapter
+lldb-dap`) to a live native process and stops it. On Linux tdb reads
+`/proc/PID/exe` to identify the language (Go, OCaml, Rust, otherwise
+C/C++) and to load symbols; pass the executable path as well to use a
+different symbol file, and pass `--lang` off Linux. `--no-pause-on-attach`
+leaves the process running, for a program about to stop itself. An
+interpreter process (python3, perl, ruby, bash) is attached as C/C++; for
+Python, Perl, and Ruby programs use `--remote-attach` instead.
+
+**Live breakpoint hook:** the C/C++ counterpart of Python's
+[`tdb.breakpoint()`](#live-breakpoint-hook). Include `tdb.h` (its directory
+is the `tdb.h dir` row of `tdb --info`) and call `tdb_breakpoint()`:
+
+```c
+#include "tdb.h"
+
+int compute(int n) {
+    int total = 0;
+    for (int i = 0; i < n; i++) total += i;
+    tdb_breakpoint();   /* tdb opens here, paused on the next line */
+    return total;
+}
+```
+
+```bash
+gcc -g -O0 -I "$(tdb --info | awk -F': ' '/tdb.h dir/ {print $2}')" -o prog prog.c
+./prog    # run it directly, not under tdb
+```
+
+When the call is reached, the program starts `tdb --lang cpp -a <its pid>
+--no-pause-on-attach` on its own terminal (the `tdb` on `PATH`, or the one
+named by `$TDB`), waits for tdb's gdb or lldb to attach, and stops in the
+hook; tdb steps out so the stop lands on the line after the call, in your
+own frame. Later calls reuse the running tdb. Quitting tdb (`Ctrl+q`)
+detaches and the program runs on; the next call opens a fresh tdb. The
+call is a no-op when stdin or stdout is not a terminal, and it warns and
+continues when `tdb` cannot be found, exits before attaching, or cannot
+attach within 60 s (Yama `ptrace_scope` 2 or 3, or a container without
+`SYS_PTRACE`, blocks attaching). If a tdb whose attach failed is still
+running, later calls warn once and return rather than open another tdb
+over it. Build with `-g -O0` so locals stay
+inspectable; a stripped binary attaches but never stops, because the hook's
+stop symbol cannot be resolved. The header is C99 and C++ compatible and
+header-only. Linux only: the hook grants ptrace access to tdb's debugger
+with `PR_SET_PTRACER`; elsewhere it warns once and returns. See
+`examples/C/breakpoint_hook_demo.c` and `examples/C++/breakpoint_hook_demo.cpp`.
 
 ### Rust
 
@@ -471,7 +587,9 @@ cargo rustc -- -C debuginfo=2 -C opt-level=0
 # Equivalent direct rustc settings: rustc -C debuginfo=2 -C opt-level=0 src/main.rs
 ```
 
-A panic that terminates the debuggee opens the error modal with the parsed
+As for C/C++, the Console view cannot feed the program's stdin (the gdb and
+lldb adapters spawn it themselves); use `--terminal` with `--adapter
+lldb-dap` for interactive programs. A panic that terminates the debuggee opens the error modal with the parsed
 panic message and backtrace; `tdb` injects `RUST_BACKTRACE=1` into launched
 programs (your own value wins if you set one) so the frames are present.
 
@@ -502,6 +620,50 @@ When source paths differ, pair `--local-root` with `--remote-root`. Do not
 expose the remote debug port to an untrusted network: prefer an SSH tunnel,
 for example `ssh -L 2345:127.0.0.1:2345 host`, then attach to `127.0.0.1:2345`.
 
+**Attach to a running process:** `tdb --lang rust -a PID` attaches gdb (or
+`--adapter lldb-dap`) to a live Rust process and stops it; tdb loads
+symbols from `/proc/PID/exe`, or from an executable path you pass as well.
+Without `--lang`, tdb recognizes a non-stripped Rust binary by its runtime
+symbols; a stripped one is debugged as C/C++.
+
+**Live breakpoint hook:** the Rust counterpart of Python's
+[`tdb.breakpoint()`](#live-breakpoint-hook). Depend on the `tdb` crate from
+this repository (it has no dependencies) and call `tdb::breakpoint()`:
+
+```toml
+[dependencies]
+tdb = { git = "https://github.com/AlDanial/tdb" }   # or path = ".../rust/tdb"
+```
+
+```rust
+fn compute(n: u64) -> u64 {
+    let total: u64 = (0..n).sum();
+    tdb::breakpoint(); // tdb opens here
+    total
+}
+```
+
+```bash
+cargo build && ./target/debug/prog    # dev profile; run it directly, not under tdb
+```
+
+When the call is reached, the program starts `tdb --lang rust -a <its pid>
+--no-pause-on-attach` on its own terminal (the `tdb` on `PATH`, or the one
+named by `$TDB`), waits for tdb's gdb or lldb to attach, and stops in the
+hook; tdb steps out so the stop lands in your own frame on, or just after,
+the call line, as the compiler's line table attributes the return address.
+Later calls reuse the running tdb. Quitting tdb (`Ctrl+q`)
+detaches and the program runs on; the next call opens a fresh tdb. The
+call is a no-op when stdin or stdout is not a terminal, and it warns and
+continues when `tdb` cannot be found, exits before attaching, or cannot
+attach within 60 s (Yama `ptrace_scope` 2 or 3, or a container without
+`SYS_PTRACE`, blocks attaching). If a tdb whose attach failed is still
+running, later calls warn once and return rather than open another tdb
+over it. Use the dev profile so locals stay
+inspectable. Linux only: the hook grants ptrace access to tdb's debugger
+with `PR_SET_PTRACER`; elsewhere it warns once and returns. See
+`examples/Rust/breakpoint_hook_demo/`.
+
 In a Rust session the Threads action (`Alt+T`, or the Threads menu entry)
 opens the Rust Concurrency workspace while the debuggee is stopped — a
 fresh, bounded snapshot of threads, wait edges, and findings. The graph is
@@ -637,11 +799,48 @@ export PERL5LIB=/opt/tdb-perl:$PERL5LIB
 the two files in the same relative layout shown above; `helpers.pl` is a
 sibling of the `Devel/` directory, not inside it.)
 
-**Pause is unavailable in attach mode.** Launch-mode sessions (`tdb
-script.pl`) support pausing a running program at any time. Remote-attach
-sessions don't. Asynchronous pause (as Python gets via `debugpy`) needs a control channel
-`Devel::TdbRemote` doesn't implement yet; `pause` in attach mode returns a
-"not available" error instead of hanging.
+**Pause in attach mode** uses a control channel: after the debug connection
+is up, `tdb` opens a second connection to the same port and asks
+`Devel::TdbRemote` to accept it. From then on `pause` (or the `p` key) writes a
+byte on that connection, the kernel delivers `SIGIO` to the debuggee, and the
+program stops at its next statement -- the same mechanism `perl5db` uses for
+Ctrl-C, so a program blocked in `sleep` or `select` is interrupted too. The
+second connection reuses the debug port, so an SSH tunnel that forwards that
+one port carries both. Requirements: the `Devel/TdbRemote.pm` copied to the
+remote host must be at least the version shipped with this feature (an older
+copy still attaches fine, but `pause` returns a "not available" error and the
+Console view says why), and the remote perl must support `O_ASYNC` (Linux,
+macOS, BSD; not Windows).
+
+**Live breakpoint hook:** the Perl counterpart of Python's
+[`tdb.breakpoint()`](#live-breakpoint-hook). Run your program normally (not
+under `tdb`) and have it open `tdb` on itself when it reaches a line of
+interest:
+
+```perl
+use Devel::TdbRemote;                 # first line of your program
+...
+Devel::TdbRemote::breakpoint();       # tdb opens here, paused on the next line
+```
+
+On the first call the program listens on an ephemeral loopback port, spawns
+`tdb --lang perl -r 127.0.0.1:PORT` on the same terminal, waits for it to
+attach, and stops on the statement after the call, in your own frame. Later
+calls reuse the running `tdb`, which simply receives another stop. Quitting
+`tdb` (`Ctrl+q`) detaches and lets the program run on; a `breakpoint()` reached
+after that spawns a fresh `tdb`. The call is a no-op when stdin/stdout are not
+a tty, so it is safe in code that sometimes runs headless, and if `tdb` cannot
+be started (not on `PATH`, or it exits before attaching) it warns and the
+program continues. `tdb` is found on `PATH`, or via the `TDB` environment
+variable. The same arming caveat as above applies: `use Devel::TdbRemote;`
+must be the first line (or use `PERL5OPT=-d:TdbRemote`), and `Devel::TdbRemote`
+has to be on `@INC`, e.g.
+
+```bash
+PERL5LIB=$(tdb --info | sed -n 's/.*Devel::TdbRemote dir *: *//p') perl prog.pl
+```
+
+See [`examples/Perl/breakpoint_hook_demo.pl`](https://github.com/AlDanial/tdb/blob/main/examples/Perl/breakpoint_hook_demo.pl).
 
 ### Bash
 
@@ -731,6 +930,33 @@ exec` integration yet.
 > race on launch; tdb detects a stalled/corrupted handshake and retries
 > once automatically with a fresh `rdbg`, so this is usually invisible.
 
+**Live breakpoint hook:** the Ruby counterpart of Python's
+[`tdb.breakpoint()`](#live-breakpoint-hook). Run your program normally (not
+under `tdb`) and have it open `tdb` on itself when it reaches a line of
+interest:
+
+```ruby
+require 'tdb'
+...
+Tdb.breakpoint          # tdb opens here, paused on the next line
+```
+
+The first call starts the debug gem's own debug server on an ephemeral
+loopback port and plants the gem's usual one-shot breakpoint on the next
+line. When that fires, the program parks and `tdb --lang ruby -r 127.0.0.1:PORT`
+is spawned on the same terminal, attaches, and shows the stop in your own
+frame. Later calls reuse the running `tdb`. Quitting `tdb` (`Ctrl+q`) detaches
+and lets the program run on; a `Tdb.breakpoint` reached after that spawns a
+fresh `tdb`. The call is a no-op when stdin/stdout are not a tty, and if `tdb`
+is not on `PATH` (or in the `TDB` environment variable) it warns and the
+program continues. Put `tdb.rb` on the load path, e.g.
+
+```bash
+RUBYLIB=$(tdb --info | sed -n 's/.*tdb.rb dir *: *//p') ruby prog.rb
+```
+
+See [`examples/Ruby/breakpoint_hook_demo.rb`](https://github.com/AlDanial/tdb/blob/main/examples/Ruby/breakpoint_hook_demo.rb).
+
 ### OCaml
 
 `tdb` debugs OCaml through two independent adapters, chosen automatically
@@ -754,7 +980,7 @@ ocamlc -g -o my_program.byte "$PWD/my_program.ml"
 ```
 
 Then, to ensure transition from bytecode to OCaml source in the
-Code view, provide an explicit temporary breakpoint (`-t`) 
+Code view, provide an explicit temporary breakpoint (`-t`)
 at the first line of execution:
 
 ```
@@ -834,6 +1060,52 @@ sessions can't `pause` a running program (so `--run` is unavailable for
 bytecode. Native sessions support `--run` normally); `Unix.fork` and Eio
 fibers are out of scope (only OCaml 5 domains are presented as threads).
 
+**Attach to a running process:** `tdb -a PID` attaches lldb-dap (or
+`--adapter gdb`) to a live native OCaml process and stops it; tdb
+recognizes the OCaml runtime in `/proc/PID/exe` and always picks a native
+adapter (bytecode programs cannot be attached to). `--no-pause-on-attach`
+leaves the process running, for a program about to stop itself.
+
+**Live breakpoint hook:** the OCaml counterpart of Python's
+[`tdb.breakpoint()`](#live-breakpoint-hook), for native code. Vendor the
+`ocaml/tdb` directory from this repository (or `opam pin` it), add
+`(libraries tdb)` to your executable's dune stanza, and call
+`Tdb.breakpoint ()`:
+
+```ocaml
+let compute n =
+  let total = ref 0 in
+  for i = 0 to n - 1 do total := !total + i done;
+  Tdb.breakpoint ();   (* tdb opens paused on this line *)
+  !total
+```
+
+```bash
+dune build && ./_build/default/prog.exe   # dev profile; run it directly, not under tdb
+```
+
+Without dune: copy `tdb.ml`, `tdb.mli`, `tdb_stubs.c`, and `tdb.h` from
+`ocaml/tdb` next to your source and build with
+`ocamlopt -g -o prog tdb_stubs.c tdb.mli tdb.ml prog.ml`.
+
+When the call is reached, the program starts `tdb --lang ocaml -a <its pid>
+--no-pause-on-attach` on its own terminal (the `tdb` on `PATH`, or the one
+named by `$TDB`), waits for tdb's lldb or gdb to attach, and stops in the
+hook, and tdb steps out of the hook's frames into your own. Unlike the
+other languages' hooks, the stop lands on the `Tdb.breakpoint ()` call
+line itself rather than the line after: both lldb and gdb map the hook's
+return address back to the call. ocamlopt also emits no debug info
+for locals, so the Variables view shows none for OCaml frames (globals
+and the stack are still available). Later calls reuse the running tdb.
+Quitting tdb (`Ctrl+q`) detaches and the program runs on; the next call
+opens a fresh tdb. The call is a no-op when stdin or stdout is not a
+terminal, and it warns and continues when `tdb` cannot be found, exits
+before attaching, or cannot attach within 60 s (Yama `ptrace_scope` 2 or
+3, or a container without `SYS_PTRACE`, blocks attaching). Keep debug
+info (`-g`, dune's dev profile). Linux only: the hook grants ptrace
+access to tdb's debugger with `PR_SET_PTRACER`; elsewhere it warns once
+and returns. See `examples/OCaml/breakpoint_hook_demo.ml`.
+
 ### Go
 
 `tdb` debugs Go through [Delve](https://github.com/go-delve/delve)'s own
@@ -859,10 +1131,53 @@ tdb -r host:port --lang go # attach to a `dlv dap --listen` already running remo
 
 `tdb --test ./pkg` debugs the package's tests under Delve's `test` mode;
 pass test-binary flags after `--`, e.g. `tdb --test ./pkg -- -run TestFoo`.
-`-a`/`--attach` currently supports Go only; on Linux, and only on Linux,
-`tdb` can identify the target as Go from `/proc/PID/exe`'s buildinfo
+`-a`/`--attach` works for Go and, through gdb/lldb-dap, for C/C++, Rust,
+and OCaml; on Linux `tdb` identifies the language from `/proc/PID/exe`
 without `--lang` (elsewhere pass `--lang go` alongside `-a`). Attaching
-stops the process immediately so you get control right away.
+stops the process immediately so you get control right away;
+`--no-pause-on-attach` leaves it running instead, for a program that is
+about to stop itself (see the live breakpoint hook below).
+
+**Entry stop:** Delve's own `stopOnEntry` halts at the process entry point
+before any goroutine exists (no stack, no source). `tdb` instead runs to
+`main.main`, so the default entry stop lands on your program's first line
+with its source on screen; `--no-stop-on-entry` skips it as usual.
+
+**Live breakpoint hook:** the Go counterpart of Python's
+`tdb.breakpoint()`. Import the `tdb` module from this repository and call
+`tdb.Breakpoint()` where you want the debugger to open:
+
+```go
+import "github.com/AlDanial/tdb/go/tdb"
+
+func compute(n int) int {
+    total := 0
+    for i := 0; i < n; i++ {
+        total += i
+    }
+    tdb.Breakpoint() // tdb opens here, paused on the next line
+    return total
+}
+```
+
+```bash
+go get github.com/AlDanial/tdb/go/tdb
+go build -gcflags=all=-N -l -o prog . && ./prog   # run it directly, not under tdb
+```
+
+When the call is reached, the program starts `tdb --lang go -a <its pid>
+--no-pause-on-attach` on its own terminal (the `tdb` on `PATH`, or the one
+named by `$TDB`), waits for tdb's Delve to attach, and traps with
+`runtime.Breakpoint()`; tdb steps out of the trap so the stop lands on the
+line after the call, in your own frame. Later `tdb.Breakpoint()` calls
+reuse the running tdb. Quitting tdb (`Ctrl+q`) detaches and the program
+runs on; the next call opens a fresh tdb. The call is a no-op when stdin
+or stdout is not a terminal, and it warns and continues when `tdb`
+cannot be found or exits before attaching. Build with
+`-gcflags=all=-N -l` so locals stay inspectable. Linux only: the hook
+grants ptrace access to tdb's Delve with `PR_SET_PTRACER` (Yama
+`ptrace_scope=1`); elsewhere it warns once and returns. See
+`examples/Go/breakpoint_hook_demo/`.
 
 **Remote attach:** start Delve's own DAP server against your program
 first —
@@ -964,6 +1279,12 @@ Notes:
   blocks attributed to tdb's own `tdb_launch.ps1` are skipped, so a bare
   `Write-Error` before the `exit` opens no modal at all.
 - `--terminal` and remote attach are not supported for PowerShell yet.
+- `Read-Host`, `$Host.UI.ReadLine()`, and `[Console]::ReadLine()` read
+  from the Console view's stdin line (pwsh is no longer started with
+  `-NonInteractive`, so mandatory-parameter and `-Confirm` prompts now wait
+  for your input there instead of failing). pwsh echoes the prompt and the
+  answer together once the line completes, so a bare `Read-Host` prompt
+  appears only after you answer it; a preceding `Write-Host` shows at once.
 - Windows PowerShell 5.1 is not supported (pwsh 7 only). Running tdb *on*
   Windows against pwsh is designed for but not yet verified (experimental).
 
@@ -973,7 +1294,7 @@ Notes:
 ┌─ Header ──────────────────────────────────────────────┐
 ├─ Menu Bar (File / Configure / Help)───────────────────┤
 │                           │                           │
-│   Code View               │  Console View (stdout)    │
+│   Code View               │  Console View (stdio)     │
 │   (source + breakpoints)  ├───────────────────────────┤
 │                           │  Variable View (tree)     │
 │                           ├───────────────────────────┤
@@ -1016,6 +1337,7 @@ A cursor line (blue) tracks your position; the current execution line is highlig
 | Key | Menu |
 |-----|------|
 | `Alt+F` | File (open a different script to debug) |
+| `Alt+E` | Edit (Save, Revert to Disk, Discard and Exit Edit Mode, Open in $EDITOR) |
 | `Alt+C` | Configure (Color Theme, Keybindings, Step Mode) |
 | `Alt+T` | Threads |
 | `Alt+P` | Processes |
@@ -1029,7 +1351,7 @@ written in the same language as the one currently being debugged.
 
 **Navigation (vim-style by default):**
 
-By default the Code View is in Debug mode.  Hit `Escape` to switch to Navigate mode
+By default the Code View is in Debug mode.  `Escape` cycles Debug → Navigate → Edit → Debug.
 In Navigate mode, you can move around the file with the following keys:
 
 | Key | Action |
@@ -1043,7 +1365,43 @@ In Navigate mode, you can move around the file with the following keys:
 | `n` / `N` | Next / previous search result |
 | `PageUp` / `PageDown` | Scroll by page |
 
-Switch from Navigate back to Debug mode with `Escape`.
+Press `Escape` again to enter Edit mode (below), and once more to return to Debug mode.
+
+**Edit mode:**
+
+Press `Escape` twice from Debug mode to open the current file in an editor
+inside the Code View. The pane title shows `[Edit]`, with `*` while there
+are unsaved changes. Editing keys follow the keybinding scheme:
+
+| Scheme | Editing style | Save | Leave Edit mode |
+|--------|---------------|------|-----------------|
+| `vim` | vim-lite: normal / insert modes, counts, `h j k l w b e 0 ^ $ gg G`, `x dd dw D yy p P u Ctrl+R J`, `i a I A o O`, `/ ? n N` | `:w` or `Ctrl+S` | `Esc` (from normal mode), `:q`, `:wq`, `:q!` |
+| `emacs` | `Ctrl+N/P/F/B`, `Alt+F/B`, `Ctrl+A/E`, `Ctrl+K` / `Ctrl+Y`, `Ctrl+_` undo, `Ctrl+S` / `Ctrl+R` search | `Ctrl+X Ctrl+S` | `Esc` or `Ctrl+X Ctrl+C` |
+| `default` (Notepad-style) | arrows, Home/End, PgUp/PgDn, Delete/Backspace, Shift+arrows to select, `Ctrl+Z`/`Ctrl+Y`, `Ctrl+X`/`Ctrl+C`/`Ctrl+V` | `Ctrl+S` | `Esc` |
+
+Leaving Edit mode, quitting, restarting, or opening another file with
+unsaved changes prompts: `s` save, `d` discard, `Esc` keep editing.
+
+Saving does not change the running program. tdb shifts your breakpoints
+to their new lines, clears the current-line marker, and (when restart is
+available) reminds you to press `R` to restart with the new code. In
+`tdb --run` sessions, which cannot restart, you will see only "Saved
+`<file>`." Edit mode is unavailable when no file is loaded, for sources
+that are not on this machine (remote attach), during replay, and in
+post-mortem mode.
+
+The `Edit` menu (`Alt+E`) offers Save, Revert to Disk, Discard and Exit
+Edit Mode, and Open in $EDITOR, which suspends tdb, runs `$VISUAL` /
+`$EDITOR` (`notepad` on Windows, `vi` otherwise) on the file, and reloads
+it when the editor exits.
+
+Syntax highlighting inside the editor needs tree-sitter, an optional
+extra: `uv pip install "textual-debugger[edit]"` (highlights Python, Bash,
+Go, and Rust; other languages edit as plain text). Highlighting in the
+normal Code View is unaffected.
+
+CRLF source files are written back with LF line endings after a save in
+Edit mode (a v1 limitation — no CRLF round-trip yet).
 
 > **Note:** Many terminals send the byte sequence `ESC+f` for `Alt+F`, which Textual's
 ANSI parser rewrites to `Ctrl+Right` (the readline "forward-word" convention).
@@ -1115,6 +1473,15 @@ Set a Python expression (e.g., `x > 10`) and/or a hit count (pause on the Nth hi
 
 Breakpoints persist across session restarts.
 
+**Breakpoints set at the debugger's own prompt (gdb):** when debugging native code
+with `gdb`, commands typed in the Evaluate Console such as `b 83` or `delete 2`
+go straight to gdb. Switching to the Breakpoint View (`Ctrl+B`, or clicking it)
+synchronizes tdb's table with gdb's list: breakpoints created at the gdb prompt
+are adopted (with their conditions and enabled state) and become ordinary tdb
+breakpoints, and breakpoints deleted at the prompt are dropped. Watchpoints,
+catchpoints and `tbreak` temporaries are left to gdb. `lldb-dap` has no such
+prompt-level breakpoint channel, so nothing to sync there.
+
 ### Variable Inspection
 
 The Variable View shows a tree of scopes with all variables in the current frame. The scopes
@@ -1128,6 +1495,39 @@ the Variables View and press `Enter`
 to display that variable in a modal.  This simplifies inspection of
 large or deeply nested data structures.
 
+#### Display list
+
+Like `gdb`'s `display` command, a variable (or any expression) can be
+pinned so its value is re-read at every stop. Pinned entries appear
+under a **Display** scope at the top of the Variables View, but only
+while they are defined in the current frame: step out of the function
+that owns `b` and the entry vanishes, step back into it and the entry
+returns. Two ways to pin, two ways to unpin:
+
+| | Evaluate Console | Variables View |
+|---|---|---|
+| pin | `display b` | right-click the variable's row |
+| unpin | `undisplay b` | left-click its row under **Display** |
+
+```
+>>> display b
+```
+
+```
+▼ Display
+    b = 6
+▼ Locals
+    a = 3
+    b = 6
+```
+
+Right-clicking a child of an expanded object pins the full path
+(`obj.count`, `items[2]`), and a bare `display` lists everything pinned.
+A click in the Variables View is recorded exactly as the typed command,
+so `--record`/`--replay` sessions reproduce it. Some terminals keep
+right-click for their own paste or context menu (Windows Terminal and
+the VS Code terminal do by default); use the `display` command there.
+
 ### Call Stack
 
 The Stack View shows the full call stack. Click a frame to navigate to its source
@@ -1155,6 +1555,45 @@ interactive evaluation of expressions in the current scope:
 ```
 
 Variable values set here are reflected in the running code.
+The Variables View redraws after every entry, so an assignment typed at
+the prompt shows up immediately rather than at the next stop.
+
+#### Interactive variables
+
+A variable *created* at the prompt is tracked and listed under an extra
+**Interactive** scope in the Variables View, alongside Locals, Globals and
+the other language-specific scopes. The value is re-read at every stop,
+so it works like a watch list of the names you introduced:
+
+```
+>>> newvar = 42
+```
+
+```
+▼ Locals
+    a = 3
+    b = 6
+▼ Interactive
+    newvar = 42
+```
+
+What counts as "created" depends on the language, and so does how long the
+variable lives:
+
+| Language | Creates an interactive variable | Lifetime |
+|---|---|---|
+| Python | `name = …` | the current frame (gone once it returns) |
+| Perl | `$name = …`, `@name = …`, `%name = …`, `our …` | the whole run (`my` lexicals vanish with the eval and are not tracked) |
+| Bash | `name=…`, `local`/`declare`/`export …` | the whole run; `local` follows the function |
+| tcsh | `set name …`, `setenv NAME …` | the whole run |
+| Ruby | `name = …`, `$name = …`, `@name = …` | globals and instance variables persist; plain locals live only in the eval's binding and read back as unavailable after the next step |
+| PowerShell | `$name = …`, `$global:name = …` | the function scope, or the whole run for `$global:` |
+| C/C++/Rust/OCaml under gdb | `set $name = …` (a gdb convenience variable) | the whole run |
+| C/C++/Rust/OCaml under lldb-dap | `int $name = …` (an lldb persistent variable) | the whole run |
+| Go (dlv), OCaml under ocamlearlybird | not possible: their evaluate cannot create variables | — |
+
+A tracked name that no longer resolves (a Python local after its frame
+returned, for example) stays in the list and shows as `<unavailable>`.
 
 ### Cut / Paste
 
@@ -1165,12 +1604,35 @@ capture mouse events for their own use.
 Instead, hold the `Shift` key while performing your conventional cut/paste keystrokes or mouse
 operation to get the expected behavior.
 
-### Console Output
+### Console Output and Input
 
 The Console View captures stdout (normal text) and stderr (red text) from the debuggee
 in real time.
 
-If your program prints a lot, or prompts for input, or uses colors or
+Programs that read from stdin (`input()`, `<STDIN>`, `read`, `gets`, …) get
+their input from the same view: while the program runs, an input line sits
+under the output log. `Ctrl+O` focuses it, `Enter` sends the line (plus a
+newline) to the program and echoes it in cyan next to the program's prompt,
+and `Ctrl+D` sends end-of-file. A bare `Enter` sends an empty line, which is
+a real answer to `input()`. The line disappears when the program exits or
+when the session has no stdin to feed.
+
+Stdin forwarding works for the languages whose program `tdb` launches on a
+pipe it owns: Python, Perl, Bash, Tcsh, Ruby, and PowerShell. It is not
+available for the compiled languages — C/C++, Rust, OCaml, and Go — because
+their adapters (`gdb -i dap`, `lldb-dap`, `dlv dap`) spawn the debuggee
+themselves and give `tdb` no handle on its stdin; the input line stays
+hidden there. It is also unavailable for remote attach (`-r`), where the
+program's stdin belongs to whoever started it, and under `--terminal`,
+where the program reads from its own terminal window. For those cases run
+the program in an external terminal with `--terminal` (launch mode only),
+or give it its input another way (a file, a pipe on the command line).
+
+Every line typed here is captured by `--record` as a `stdin` gesture and
+replayed by `--replay`/`--replay-tui`, and the JSON-RPC server exposes the
+same thing as the `stdin` / `stdin_eof` actions.
+
+If your program prints a lot, or uses colors or
 terminal control codes, run the program in an external terminal
 with `--terminal` for a better experience.
 The `--terminal` switch requires a graphical environment and a compatible
@@ -1282,6 +1744,12 @@ This behavior matches hitting `c` while in a conventional (that is, the Python
 standard library's) `breakpoint()` session.
 If you want to kill the program instead, use `Ctrl+c` in the terminal running the debuggee.
 
+Perl, Ruby, Go, C/C++, Rust, and OCaml programs get the same hook as
+`Devel::TdbRemote::breakpoint()`, `Tdb.breakpoint`, `tdb.Breakpoint()`,
+`tdb_breakpoint()`, `tdb::breakpoint()`, and `Tdb.breakpoint ()`; see
+[Perl](#perl), [Ruby](#ruby), [Go](#go), [C/C++ tips](#cc-tips),
+[Rust](#rust), and [OCaml](#ocaml).
+
 ### Async Task Inspector
 
 For programs using `asyncio`, the menu bar shows an **Async Tasks (N)** label with the count of
@@ -1470,7 +1938,8 @@ terminal around.
 The debuggee runs in a separate window of the specified terminal, including
 all of its stdin/stdout/stderr. Keyboard input, program output, and
 anything the program itself draws to the terminal all happen in that
-window, not in `tdb`'s Console View. Supported choices:
+window, not in `tdb`'s Console View (whose stdin line is hidden in this
+mode). Supported choices:
 `xterm`, `konsole`, `gnome-terminal`, `ghostty`, `kitty`, `iterm2`, `warp`,
 `wezterm`, `terminator`. The selected terminal must be on `PATH`. Debugging
 (breakpoints, stepping, variable inspection, the evaluate console) proceeds
@@ -1480,39 +1949,31 @@ This feature only works in graphical environments where external terminals are a
 
 ### Run Mode (`--run`)
 
-`tdb`'s run mode invokes an unmodified program nearly at full speed, without bringing up the TUI.
-At any point afterwards, hitting `Ctrl-C` in that terminal pauses the program
-and drops you into the full TUI.
-From there you can inspect the program's state, navigate the stack, set and continue
-to breakpoints, and so on.  After you finish inspecting, hitting `q` to quit brings up
-a modal that lets you either detach from the TUI and let the program resume running,
-or lets you terminate it.
+`tdb`'s run mode acts as a job shepherd.
+It runs your unmodified program at nearly full speed, without bringing up the TUI,
+and listens for two interrupt signals:
 
-The primary use cases for run mode are: (1) allowing inspection of a program that
-appears hung, and (2) finding where a program execution path lands after it
-receives a problematic input.
+- `Ctrl-C` pauses the program and brings up TUI, placing you at the currently
+active line of code.  From there you can debug interactively as usual.  When
+you quit the TUI, you can either detach and let the program continue running, or terminate it.
+
+- `Ctrl-\` temporarily pauses the program and prints a JSON-formatted stack trace to stdout
+or a log file, then resumes the program.
 
 ```bash
 tdb --run my_program.py args...
 ```
 
-The debuggee's stdout/stderr stream straight to the terminal. If the program exits on
+The debuggee's stdout/stderr stream straight to the terminal, and for the
+languages with stdin forwarding (see
+[Console Output and Input](#console-output-and-input)) the program reads
+its stdin from that terminal too. If the program exits on
 its own, `tdb` exits with the same code:
 
 ```bash
 tdb --run my_program.py; echo $?   # my_program.py's own exit code
 ```
 
-**Interrupting:** press Ctrl-C in the terminal (any platform), or, on Unix, send
-`SIGUSR1` to `tdb`'s pid from another terminal: `kill -USR1 <tdb pid>`. Either one pauses
-the debuggee at its currently executing line and opens the TUI with full debugging
-available (breakpoints, stepping, variable inspection, the evaluate console). The
-debuggee itself never receives the signal (`tdb`'s adapter runs in its own process
-group), so its own `SIGINT` handling is undisturbed.
-
-**Examining without opening the TUI:** press `Ctrl-\` in the terminal (`Ctrl-Break` on
-Windows), or, on Unix, send `SIGUSR2` to `tdb`'s pid: `kill -USR2 <tdb pid>`.
-
 **Windows caveat:** the Ctrl-Break trigger is untested. Unlike Ctrl-C, a console
 Ctrl-Break is delivered to every process attached to the console, including the debug
 adapter and the program itself, so it may terminate the program instead of snapshotting
@@ -1587,9 +2048,14 @@ blocking external call or syscall, the pause can't land until that call returns
 
 ### Eval Mode (`-e`/`--eval`)
 
-Eval mode automates a common debugging loop--set a breakpoint, run to it,
-evaluate an expression in the Evaluate console, continue--without
-opening the TUI. `-e` takes two arguments, a location and an expression:
+Eval mode is essentially a code injection mechanism.  Rather than injecting
+native code though, only expressions that are valid in the Evaluate View
+can be injected (in Python, native expressions are processed correctly
+in the Evaluate View).
+
+In this way, Eval mode automates the common debugging action of setting a
+breakpoint, running to it, evaluating (and printing the result of) an expression, then
+resuming execution, all without opening the TUI. `-e` takes two arguments, a location and an expression:
 
 ```bash
 tdb --eval examples/digits_of_pi.py:25 "print(f'{nr=}')" examples/digits_of_pi.py
@@ -1609,7 +2075,7 @@ evaluated in each child process that reaches it.
 - `-e` may be repeated to plant several eval points in one run.
 - The expression is evaluated through the debug adapter (DAP `evaluate`,
   context `repl`), just like the Evaluate console: side effects are real
-  and persist in the running program, for example 
+  and persist in the running program, for example
   `-e my_program.py:25 "limit = 10"` changes `limit` from line 25 onward.
 - A bare expression's result is printed to stdout; statement-style
   expressions (`print(...)`, assignments) print nothing beyond their own
@@ -1632,7 +2098,7 @@ evaluated in each child process that reaches it.
 ```bash
 tdb --keybindings vim my_program.py    # default
 tdb --keybindings emacs my_program.py
-tdb --keybindings default my_program.py
+tdb --keybindings default my_program.py   # Notepad-style editing
 ```
 
 The keybinding choice is saved to `~/.config/tdb/config.json` and remembered for subsequent
@@ -1714,6 +2180,8 @@ curl -s -X POST http://127.0.0.1:8150/rpc \
 | `stack_down` | `[]` | Move down the call stack |
 | `get_stack_trace` | `[]` | Full call stack |
 | `get_output` | `[]` | Drain buffered stdout/stderr |
+| `stdin` | `["line"]` | Send a line (newline appended) to the program's stdin; errors when the session has no stdin (compiled languages, `--terminal`, remote attach) |
+| `stdin_eof` | `[]` | Close the program's stdin (Ctrl+D) |
 | `get_source` | `["file_path"]` | Read a source file |
 | `list_threads` | `[]` | List all threads |
 | `inspect_thread` | `[thread_id]` | Inspect a specific thread |
@@ -1741,7 +2209,8 @@ Each is JSON with `event`, `data`, and `timestamp` fields.
 
 `tdb --record session.jsonl prog.py` runs a normal TUI session and captures
 your debugging actions including breakpoints (including `-k`/`-t` and persisted
-ones), stepping, continue/pause, Evaluate-console entries, stack-frame
+ones), stepping, continue/pause, Evaluate-console entries, lines typed into
+the Console view for the program's stdin (and Ctrl+D), stack-frame
 navigation, variable expansion, restart, quit. The session is
 written to `session.jsonl` as
 JSON-RPC commands. Works with launch mode (any language) and `-r`
@@ -1894,6 +2363,7 @@ usage: tdb [-h] [-v] [-r [HOST:]PORT] [--cwd CWD] [--no-stop-on-entry]
 | Flag | Description |
 |------|-------------|
 | `-r HOST:PORT` | Attach to a remote debugpy server |
+| `-a`, `--attach PID` | Attach to a running local process by pid: Go (Delve) or a native C/C++, Rust, or OCaml program (gdb or lldb-dap). Linux identifies the language from `/proc/PID/exe`; elsewhere pass `--lang` and, for native programs, the executable path. |
 | `--local-root PATH` | Local directory containing a copy of remote code (repeat to mirror multiple trees). Pair with `--remote-root`; counts must match. Required when `-k` sets a breakpoint against a remote debuggee whose code lives at a different path. |
 | `--remote-root PATH` | Remote directory matched to `--local-root` (same CLI position via `zip()`). |
 | `-k`, `--breakpoint FILE:LINE|LINE` | Set a breakpoint (may be repeated). Passing `-k` implies `--no-stop-on-entry` so the program runs straight to the first breakpoint. |
@@ -1903,14 +2373,14 @@ usage: tdb [-h] [-v] [-r [HOST:]PORT] [--cwd CWD] [--no-stop-on-entry]
 | `--python PATH` | Python interpreter for the debuggee (Python targets only) |
 | `--pv` | Shorthand for --python .venv/bin/python |
 | `--lang LANGUAGE` | Debuggee language (`python`, `cpp`, `perl`); default: auto-detect from the target |
-| `--adapter ADAPTER` | Debug adapter within the language (e.g. `--lang cpp --adapter lldb-dap`); default: the language's standard adapter |
+| `--adapter ADAPTER` | Debug adapter within the language (e.g. `--lang cpp --adapter lldb-dap`), or a full path to a `gdb`/`lldb-dap`/`dlv` executable to use instead of the one on `PATH`; default: the language's standard adapter |
 | `--no-just-my-code` | Step into stdlib/site-packages code instead of skipping it
   (default: skipped). On uncaught exceptions, the crash modal always shows the full traceback
   including library frames, regardless of this flag. |
 | `--no-subprocess` | Disable debugpy's subprocess tracking (use when debugging `tdb` itself) |
 | `--terminal TERM` | Run debuggee in the named external terminal: `xterm`, `konsole`,
   `gnome-terminal`, `ghostty`, `kitty`, `iterm2`, `warp`, `wezterm`, or `terminator` |
-| `--keybindings SCHEME` | `default`, `vim`, or `emacs` (saved to config) |
+| `--keybindings SCHEME` | `vim`, `emacs`, or `default` (Notepad-style editing); saved to config |
 | `--server` | Enable JSON-RPC server alongside TUI |
 | `--headless` | JSON-RPC server only, no TUI |
 | `--server-port PORT` | Server port (default: 8150) |
@@ -1934,10 +2404,63 @@ On Windows, it uses `%APPDATA%\tdb\`.
 | `config.json` | User preferences (keybinding scheme, color theme, step mode, adapter overrides) |
 | `breakpoints.json` | Breakpoints from previous sessions, keyed by project directory |
 
+### Sample `config.json`
+
+Every key `tdb` reads, with its default or a representative value. Copy
+this to restore a deleted or corrupted file, then delete the entries you
+don't need: a missing key takes its default, an unknown key is ignored,
+and an invalid value (say a misspelled `step_mode`) falls back to the
+default instead of stopping `tdb`.
+
+```json
+{
+  "keybindings": "vim",
+  "theme": null,
+  "step_mode": "statement",
+  "adapters": {
+    "gdb": "/usr/bin/gdb",
+    "lldb-dap": null,
+    "dlv": "/home/me/go/bin/dlv",
+    "perl": "/usr/bin/perl",
+    "rdbg": "/usr/local/bin/rdbg",
+    "bash": "/usr/bin/bash",
+    "tcsh": "/usr/bin/tcsh",
+    "pwsh": "/usr/bin/pwsh",
+    "pses": "/home/me/.local/share/PowerShellEditorServices",
+    "ocamlearlybird": "/home/me/.opam/default/bin/ocamlearlybird"
+  },
+  "default_adapters": {
+    "cpp": "gdb",
+    "rust": "gdb",
+    "ocaml": "lldb-dap"
+  }
+}
+```
+
+| Key | Values | Meaning |
+|-----|--------|---------|
+| `keybindings` | `"vim"` (default), `"emacs"`, `"default"` | Code View keybinding scheme; also set by `--keybindings` |
+| `theme` | `null` (default) or a Textual theme name such as `"textual-dark"`, `"textual-light"`, `"nord"`, `"gruvbox"`, `"dracula"`, `"monokai"`, `"tokyo-night"`, `"catppuccin-mocha"` | Color theme; the names offered under **Configure > Theme** are the valid ones, and an unknown name is ignored |
+| `step_mode` | `"statement"` (default), `"line"` | How `n`/`s` treat multi-line statements (see **Step mode** below) |
+| `adapters` | adapter id → executable path, or `null` | Where to find a debugger or interpreter instead of searching `PATH`. Ids: `gdb`, `lldb-dap`, `dlv` (debuggers); `perl`, `rdbg`, `bash`, `tcsh`, `pwsh` (interpreters `tdb` spawns); `pses` (the PowerShell Editor Services module directory); `ocamlearlybird`. Only list the ones you need |
+| `default_adapters` | language id → adapter id | Which adapter a language uses when `--adapter` isn't given. Languages with a choice: `cpp` and `rust` (`gdb` or `lldb-dap`), `ocaml` (`lldb-dap`, `gdb`, or `ocamlearlybird`) |
+
+The file is plain JSON: no comments, no trailing commas. `tdb` rewrites it
+when you change a setting from the **Configure** menu, so hand edits made
+while `tdb` is running may be overwritten.
+
 Adapter-related keys in `config.json`: `adapters` maps an adapter id to an
 executable path (`{"adapters": {"lldb-dap": "/opt/llvm/bin/lldb-dap"}}`), and
 `default_adapters` picks a language's default adapter
-(`{"default_adapters": {"cpp": "lldb-dap"}}`).
+(`{"default_adapters": {"cpp": "lldb-dap"}}`). For a one-off run,
+`--adapter /path/to/gdb` (or `lldb-dap`, `dlv`) overrides the `adapters` entry
+without editing the file; `tdb --info` reports the `gdb` and `lldb-dap`
+currently resolved (config override first, then `PATH`) with their versions.
+
+When `tdb` creates `config.json` for the first time it seeds `adapters` with
+`gdb` and `lldb-dap` entries pointing at the executables found on `PATH`
+(`null` when one isn't installed) so the keys are there to edit. A `null`
+entry behaves like a missing one: `tdb` falls back to `PATH`.
 
 **Perl is a special case:** `perl-tdb` is tdb's own bundled adapter (always
 found; it's Python code, not an external executable), so
@@ -2000,6 +2523,7 @@ as open source.
 
 - OpenAI, for providing access to Codex through the
 [Codex for Open Source](https://developers.openai.com/community/codex-for-oss) program.
+Codex was used to implement tcsh and Rust support.
 
 This project was inspired by Andreas Klöckner's excellent [pudb](https://pypi.org/project/pudb/)
 Python debugger.