diff --git a/README.md b/README.md
index 0380ff8..b0fd2da 100644
--- a/README.md
+++ b/README.md
@@ -40,6 +40,9 @@ nib ls --tag ops
 # list a specific month
 nib ls --month 2026-05
 
+# terminal UI
+nib tui
+
 # start the web UI
 nib serve
 ```
@@ -122,9 +125,22 @@ Or use `^type` inline: `nib "proxy trick #nginx ^card"`
 | `nib absorb <target> <source>` | Merge source into target |
 | `nib delete <id>` | Soft delete (repeat to hard delete) |
 | `nib serve` | Start web UI on `:4444` (or `--port`) |
+| `nib tui` | Launch the terminal UI |
 
 IDs are prefix-matchable. If `01KRQ4` is unique, that's enough.
 
+## Terminal UI
+
+`nib tui` launches a keyboard-driven interface in your terminal.
+
+- **Stream view** — entries grouped by date with compact gutter headers
+- **Cards view** — promoted cards filtered by intent (grab/read/fill), sorted by usage
+- **Split-pane detail** — wide terminals (100+ cols) show list and detail side-by-side
+- **Capture drawer** — inline add with live preview of parsed entity
+- **Search** — type `?query #tag` in the capture bar to filter
+
+Navigation: `j`/`k` move, `enter` opens detail, `h`/`l` switch panes, `a` to add, `?` for full keybindings.
+
 ## Web UI
 
 `nib serve` starts a local web interface with:
diff --git a/docs/development.md b/docs/development.md
index 3005e4e..352af66 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -77,6 +77,16 @@ For production, use a reverse proxy (Caddy, nginx) with real certificates in fro
 
 Override with `--port` or the `NIB_PORT` environment variable.
 
+## Terminal UI
+
+Run the TUI directly from source:
+
+```sh
+go run . tui
+```
+
+TUI code lives in `internal/tui/`. No live-reload — restart manually after changes.
+
 ## Typical Workflow
 
 1. `make cert` — once, generates dev TLS cert