docs: refresh tabs and keybind docs

4 files changed, 43 insertions, 6 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6d347a55..1ebe34c6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,7 +3,18 @@
 ## Unreleased
 
 ### Added
+- Added tabs within workspaces, so a single workspace can now hold multiple terminal tab contexts with their own pane layouts.
 - Added optional direct pane-focus keybindings for terminal mode, so you can switch panes with modifier shortcuts like `alt+h` or `alt+right` without entering navigate mode first.
+- Added built-in direct integrations for pi, claude code, codex, and opencode, with install/uninstall commands under `herdr integration ...`.
+- Added authoritative hook-driven state reporting support, so pane state can be updated directly from agent integrations instead of relying only on heuristics.
+
+### Changed
+- Refactored keybind discoverability so the in-app keybind help now shows all supported actions, including optional bindings that are currently unset.
+- Keybind help now uses a centered scrollable modal with mouse and keyboard scrolling, matching the release-notes interaction model more closely.
+- Popups and action-button interactions were refactored to use more consistent modal geometry and button semantics across the ui.
+
+### Documentation
+- Updated the README, configuration guide, and socket api docs to reflect tabs, unset optional keybindings, direct terminal-mode navigation examples, and the current workspace-scoped pane id model.
 
 ## [0.2.4] - 2026-04-01
 
diff --git a/CONFIGURATION.md b/CONFIGURATION.md
index 63034f13..9c2ba770 100644
--- a/CONFIGURATION.md
+++ b/CONFIGURATION.md
@@ -43,6 +43,7 @@ supported syntax:
 notes:
 - most reliable bindings are plain keys, `ctrl+letter`, `esc`/`tab`/`enter`, and function keys
 - `alt+...` and punctuation-with-modifiers may vary depending on terminal/tmux setup
+- bindings marked `unset` in the key reference are supported actions with no default key assigned
 - for navigate-mode actions, duplicate keybindings are treated as config errors; later conflicting bindings fall back to defaults
 
 example:
@@ -53,14 +54,21 @@ prefix = "ctrl+b"
 new_workspace = "n"
 rename_workspace = "shift+n"
 close_workspace = "d"
+new_tab = "c"
 split_vertical = "v"
 split_horizontal = "-"
 close_pane = "x"
 fullscreen = "f"
 resize_mode = "r"
 toggle_sidebar = "b"
+previous_workspace = "ctrl+alt+["
+next_workspace = "ctrl+alt+]"
+previous_tab = "alt+["
+next_tab = "alt+]"
 focus_pane_left = "alt+h"
-focus_pane_right = "alt+right"
+focus_pane_down = "alt+j"
+focus_pane_up = "alt+k"
+focus_pane_right = "alt+l"
 ```
 
 ### key reference
diff --git a/README.md b/README.md
index 3eee25f2..4f94ab27 100644
--- a/README.md
+++ b/README.md
@@ -145,23 +145,38 @@ on first run, herdr opens a short onboarding flow so you can choose your notific
 
 press `n` to create your first workspace. it opens immediately as a new terminal context in your current project context, and herdr labels it automatically from the root pane's repo or folder.
 
-press `ctrl+b` (the prefix key) to switch back to navigate mode. from there you can manage workspaces and panes.
+press `ctrl+b` (the prefix key) to switch back to navigate mode. from there you can manage workspaces, tabs, and panes.
 
 ### navigate mode (prefix: ctrl+b)
 
-navigate mode is the workspace control layer. movement actions stay in navigate mode; mutating actions like split, close, new workspace, and sidebar toggle return you to terminal mode.
+navigate mode is the workspace control layer. a workspace can contain multiple tabs, and each tab can contain multiple panes. movement actions stay in navigate mode; mutating actions like split, close, new workspace, new tab, and sidebar toggle return you to terminal mode.
 
 common defaults:
 - `n` new workspace
 - `shift+n` rename workspace
 - `d` close workspace
+- `c` new tab
 - `v` / `-` split pane
 - `x` close pane
 - `f` fullscreen
 - `r` resize mode
 - `b` toggle sidebar
 
-optional direct bindings can also switch workspaces, tabs, or panes from terminal mode without going through the prefix first. for example, you can bind `focus_pane_left = "alt+h"` or `focus_pane_right = "alt+right"` in your config.
+optional direct bindings are available but **unset by default**. you can bind workspace, tab, and pane switching directly in terminal mode without going through the prefix first.
+
+example:
+
+```toml
+[keys]
+previous_workspace = "ctrl+alt+["
+next_workspace = "ctrl+alt+]"
+previous_tab = "alt+["
+next_tab = "alt+]"
+focus_pane_left = "alt+h"
+focus_pane_down = "alt+j"
+focus_pane_up = "alt+k"
+focus_pane_right = "alt+l"
+```
 
 full keybinding and config reference: [`CONFIGURATION.md`](./CONFIGURATION.md)
 
@@ -187,6 +202,7 @@ this is the core loop of herdr: scan the workspace list, drop into the right con
 mouse support is built in. herdr is not keyboard-only.
 
 - click a workspace in the sidebar to switch
+- click tabs to switch within the active workspace
 - click a pane to focus it
 - drag split borders to resize
 - drag in a pane to select text; release to copy it to your system clipboard
@@ -225,7 +241,7 @@ for all keybindings, onboarding, notification, sound, ui options, and environmen
 
 ## session persistence
 
-herdr saves your workspace layout, pane working directories, and focused pane on exit. when you restart, everything is restored. sessions are stored at `~/.config/herdr/session.json`.
+herdr saves your workspaces, tabs, pane layouts, pane working directories, and focused tab/pane on exit. when you restart, everything is restored. sessions are stored at `~/.config/herdr/session.json`.
 
 use `--no-session` to start fresh.
 
@@ -304,7 +320,7 @@ herdr's workspace, pane, and wait commands are documented in [`SOCKET_API.md`](.
 workspace ids are compact public ids like `1`, `2`, `3`.
 pane ids are compact public ids like `1-1`, `1-2`, `2-1`.
 
-they are positional within the current live session, so numbering compacts when workspaces or panes are closed.
+even with tabs enabled, pane ids remain workspace-scoped public ids rather than `workspace-tab-pane` triples. they are positional within the current live session, so numbering compacts when workspaces or panes are closed.
 
 ## building from source
 
diff --git a/SOCKET_API.md b/SOCKET_API.md
index 333da511..cff166c5 100644
--- a/SOCKET_API.md
+++ b/SOCKET_API.md
@@ -87,6 +87,8 @@ that means:
 
 these are compact public ids for the current live session. they are **not durable database ids**. if a workspace or pane closes, higher numbers compact down.
 
+herdr now supports tabs inside workspaces in the ui, but pane ids remain workspace-scoped public ids like `1-2` rather than `workspace-tab-pane` triples. tabs are not exposed as first-class socket api objects yet.
+
 ## core objects
 
 `workspace_info` responses contain objects like: