diff --git a/README.md b/README.md
index 2da5d65..363229c 100644
--- a/README.md
+++ b/README.md
@@ -1,44 +1,85 @@
+
+
# tmux-attach-browser
+**Choose or create a tmux session with one command.**
+
[](https://github.com/hmmhmmhm/tmux-attach-browser/actions/workflows/ci.yml)
-[](https://github.com/hmmhmmhm/tmux-attach-browser/releases)
-[](LICENSE)
+[](https://github.com/hmmhmmhm/tmux-attach-browser/releases/latest)
+[](go.mod)
+[](LICENSE)
+
+
+
+## Install
+
+Already have [tmux](https://github.com/tmux/tmux) on your `PATH`? Install the latest release on macOS, Linux, or Windows WSL2:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/hmmhmmhm/tmux-attach-browser/main/install.sh | sh
+```
-Browse, create, and enter tmux sessions with one command: `tab`.
+The installer verifies the release checksum and places `tab` in `~/.local/bin`. It never runs `sudo`.
+
+## Run `tab`
```text
-tmux sessions
+$ tab
+
+ tmux sessions
+
+ 4 sessions
-> work
- 3 windows | 1 attached | active 2026-07-19 14:03:00
+│ work
+│ 3 windows | 1 attached | active 2026-07-19 18:32:26
+
+ personal-agent
+ 2 windows | detached | active 2026-07-19 18:31:07
api
- 2 windows | detached | active 2026-07-19 11:42:00
+ 2 windows | detached | active 2026-07-19 18:27:44
+
+ docs
+ 1 window | detached | active 2026-07-19 18:20:03
- ↑/k up ↓/j down / filter n new session r refresh ? more
+ ↑/k up • ↓/j down • / filter • n new session • r refresh • q quit • ? more
```
-`tab` is a focused terminal UI built with [Bubble Tea](https://github.com/charmbracelet/bubbletea) and the Bubbles [list](https://github.com/charmbracelet/bubbles/tree/main/list) and [textinput](https://github.com/charmbracelet/bubbles/tree/main/textinput) components.
+That is the whole workflow:
-## Features
+1. Run `tab` to see your tmux sessions.
+2. Select a session and press Enter to enter it.
+3. Press `n` to create a session in the current directory.
-- Fuzzy-search current tmux sessions.
-- See window count, attached clients, and recent activity.
-- Attach with Enter.
-- Create a session in the current directory with `n`.
-- Refresh without leaving the browser.
-- Switch clients when already inside tmux, avoiding nested sessions.
-- Install verified release binaries on macOS, Linux, and Windows.
+To skip the browser and open a named session directly:
-## Requirements
+```sh
+tab work
+```
-`tab` controls an existing tmux installation. Install tmux first:
+When `tab` runs inside tmux, it switches the current client to your chosen session instead of nesting another tmux client.
+
+## Keys
+
+| Key | Action |
+| --- | --- |
+| Up, Down, `j`, `k` | Select a session |
+| Enter | Enter the selected session |
+| `n` | Create a session in the current directory |
+| `/` | Filter sessions by name |
+| `r` | Refresh the session list |
+| `?` | Show or hide expanded help |
+| Esc | Cancel filtering or session creation; quit from the session list |
+| `q`, Ctrl+C | Quit |
+
+
+Install tmux
```sh
# macOS
brew install tmux
-# Ubuntu or Debian
+# Ubuntu or Debian, including WSL2
sudo apt update && sudo apt install tmux
# Fedora
@@ -48,133 +89,67 @@ sudo dnf install tmux
sudo pacman -S tmux
```
-Windows 10 and 11 are supported through WSL2. Run `wsl --install`, open the installed Linux distribution, install tmux there, and then use the Linux installation command below.
-
-The native Windows binary is provided for advanced MSYS2 or Cygwin environments where `tmux.exe` is already on PATH. WSL2 is the tested and recommended Windows setup.
+
-## Install
+
+Other installation options
-### macOS, Linux, and Windows WSL2
+Choose another writable installation directory:
```sh
-curl -fsSL https://raw.githubusercontent.com/hmmhmmhm/tmux-attach-browser/main/install.sh | sh
+curl -fsSL https://raw.githubusercontent.com/hmmhmmhm/tmux-attach-browser/main/install.sh | TAB_INSTALL_DIR="$HOME/bin" sh
```
-The installer downloads the latest release, verifies its SHA-256 checksum, and places `tab` in `$HOME/.local/bin`. Choose another directory with `TAB_INSTALL_DIR`:
+Add the directory to your `PATH` if your shell does not already include it.
+
+Install with Go 1.25 or newer:
```sh
-curl -fsSL https://raw.githubusercontent.com/hmmhmmhm/tmux-attach-browser/main/install.sh | TAB_INSTALL_DIR=/usr/local/bin sh
+go install github.com/hmmhmmhm/tmux-attach-browser/cmd/tab@latest
```
-The installer never runs `sudo` automatically.
-
-### Native Windows PowerShell
-
-Use this only when tmux is already available in the same environment:
+Native Windows PowerShell is intended for MSYS2 or Cygwin environments where `tmux.exe` is already available:
```powershell
curl.exe -fsSL https://raw.githubusercontent.com/hmmhmmhm/tmux-attach-browser/main/install.ps1 | powershell -NoProfile -ExecutionPolicy Bypass -Command -
```
-The default destination is `$HOME\.local\bin\tab.exe`. Set `TAB_INSTALL_DIR` before running the command to change it.
+WSL2 remains the recommended Windows setup.
-### Go
+
-With Go 1.25 or newer:
+
+Troubleshooting
-```sh
-go install github.com/hmmhmmhm/tmux-attach-browser/cmd/tab@latest
-```
+### `tab: command not found`
-## Usage
+The default installer destination is `~/.local/bin`. Add it to your shell profile, then open a new terminal:
```sh
-# Open the session browser
-tab
-
-# Attach directly without opening the browser
-tab work
-
-# Print version or help
-tab --version
-tab --help
+export PATH="$HOME/.local/bin:$PATH"
```
-### Keys
-
-| Key | Action |
-| --- | --- |
-| Up, Down, `j`, `k` | Move through sessions |
-| Enter | Attach to the selected session |
-| `n` | Create a new session in the current directory |
-| `/` | Filter sessions by name |
-| `r` | Refresh the session list |
-| `?` | Expand or collapse help |
-| Esc | Cancel filtering or session creation |
-| `q`, Ctrl+C | Quit |
-
-Session names cannot be blank or contain `:` or `.`. tmux rewrites or interprets these characters in target names, so `tab` rejects them before creating a session.
-
-## How it works
-
-`tab` asks tmux for a tab-separated session list, then renders it through the Bubbles list component. Selecting an existing session exits Bubble Tea before starting the interactive tmux client, so the terminal is restored correctly.
+### `tmux is not installed or is not on PATH`
-Outside tmux, selection runs:
+Install tmux using the commands above, then confirm that `tmux -V` works in the same terminal.
-```sh
-tmux attach-session -t SESSION
-```
-
-Inside tmux, it runs:
+### `tab: connect to session: exit status 1`
-```sh
-tmux switch-client -t SESSION
-```
+The session may have ended after the list was loaded. Run `tab` again or press `r` before selecting.
-New sessions are created detached with `tmux new-session -d -s SESSION -c CURRENT_DIRECTORY` and attached after the UI exits.
+
-## Build and test
+
+Build and verify
```sh
git clone https://github.com/hmmhmmhm/tmux-attach-browser.git
cd tmux-attach-browser
-go test ./...
go test -race ./...
go vet ./...
go build -o tab ./cmd/tab
```
-Additional checks:
-
-```sh
-sh scripts/test-install.sh
-sh scripts/tmux-smoke.sh
-goreleaser check
-goreleaser release --snapshot --clean
-```
-
-## Troubleshooting
-
-### `tmux is not installed or is not on PATH`
-
-Install tmux using the platform instructions above, then confirm `tmux -V` works in the same terminal where you run `tab`.
-
-### `tab: connect to session: exit status 1`
-
-The session may have ended after the list was loaded. Run `tab` again or press `r` before selecting.
-
-### `$HOME/.local/bin` is not on PATH
-
-Add this line to your shell profile:
-
-```sh
-export PATH="$HOME/.local/bin:$PATH"
-```
-
-## Contributing
-
-See [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports and focused feature proposals are welcome.
-
-## License
+
-[MIT](LICENSE)
+Built with [Bubble Tea](https://github.com/charmbracelet/bubbletea). Contributions are described in [CONTRIBUTING.md](CONTRIBUTING.md). Licensed under the [MIT License](LICENSE).