docs: the tab bar's new shapes, written down

A 'The tab bar' section on the panes page: the sidebar, its four knobs,
the status rows under each tab, and the borrowed directory name for
unnamed tabs. The config page's knob table learns the tab_bar_* keys.

scripting.md and the driving-slosh skill stop underselling the status
verb: it was documented back when the pane's own frame was the only
place a status could appear, which made it decoration. With the
sidebar it is how a pane reports progress to somebody working in
another tab -- so say that, and say to keep it current and clear it
when the work is done.

3 files changed, 41 insertions, 1 deletions

diff --git a/docs/config.md b/docs/config.md
index e393f6f..4b964ac 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -83,7 +83,7 @@ theme { frame_focus "#00ff88" }     // ...but that one colour is mine
 | group     | what is in it                                                                                                                                                                                                                                                                      |
 | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | geometry  | `gap` `gap_aspect` `padding` `compact` `rounded` `title_align` `title_inset` `min_pane` `min_split`                                                                                                                                                                                |
-| chrome    | `status_bar` `status_line` `status_pad` `hints` `version_banner` `pane_buttons` `bell_indicator` and the marks (`zoom_mark` `zoom_on_mark` `close_mark` `min_mark` `newtab_mark` `bell_mark`)                                                                                      |
+| chrome    | `status_bar` `status_line` `status_pad` `tab_bar_side` `tab_bar_width` `tab_bar_pad` `tab_bar_status` `hints` `version_banner` `pane_buttons` `bell_indicator` and the marks (`zoom_mark` `zoom_on_mark` `close_mark` `min_mark` `newtab_mark` `bell_mark`)                        |
 | behaviour | `focus_follows_mouse` `ctrl_d_exits` `scroll_lines` `scrollback` `scrollback_bytes` `toast_ms` `splash_ms` `hover_delay_ms` `double_click_ms` `word_separators` `anim_ms` `modal_scrim` `dim_unfocused` `float_shadow` `keep_dead` `in_band_shaders` `multi_attach` `attach_indicator` `size_follows` `shell` `editor` |
 | projects  | `project_roots` `project_layout` (see [workspaces](workspaces.md))                                                                                                                                                                                                                 |
 | colour    | `theme { }`                                                                                                                                                                                                                                                                        |
diff --git a/docs/panes.md b/docs/panes.md
index 2066f2a..dd3fdba 100644
--- a/docs/panes.md
+++ b/docs/panes.md
@@ -48,6 +48,40 @@ looking at is drawn.
 - **Click a tab to switch**, `+` to open one, a pane to focus it, and the marks in a
   frame's corner to minimise (`▬`), zoom (`□`) or close (`✕`) it.
 
+## The tab bar
+
+The strip of tabs sits along the top by default. It does not have to:
+
+```kdl
+tab_bar_side "left"   // or "right"; "top" is the default
+tab_bar_width 18      // columns the sidebar takes
+tab_bar_pad 1         // blank rows above the first tab
+```
+
+A **sidebar lists one tab per row** down the chosen edge, and the panes trade
+the strip's row for its columns. Everything the strip does travels with it:
+click to switch, double-click to rename in place, drag a pane onto a tab or
+onto the `+`, drag tabs to reorder. The pane count and the prefix badge move
+to the sidebar's bottom rows; the [status line](config.md) along the bottom
+keeps the full width. A terminal too narrow to give up the columns falls back
+to the top row until it grows.
+
+**Under each tab, the sidebar says what the panes inside are up to.** A pane
+that announced a status over [OSC 5577](scripting.md#a-pane-can-draw-its-own-chrome)
+puts that line under its tab — visible from every other tab, which is the
+point — and a pane that died shows how instead (`exited: status 3`). At most
+`tab_bar_status` rows per tab (3 by default, 0 turns it off); more than that
+and the last row is an ellipsis rather than a status pretending the list is
+complete. **Clicking a status row jumps to the pane that said it**, across
+tabs. The top strip has one row and no room for any of this, which is half of
+why the sidebar exists.
+
+**An unnamed tab borrows the directory its focused pane is in** — the
+kernel's answer, so a `cd` moves the label with you, and home shows as `~`.
+A real name or a [purpose](layouts.md#purposes) wins the moment one exists;
+when a tab's panes sit in different directories, the focused one names the
+tab. This holds wherever the bar sits, top row included.
+
 ## Floating a pane
 
 `C-a f` lifts a pane out of the layout and draws it on top of the tiled ones
diff --git a/docs/scripting.md b/docs/scripting.md
index 5ae448f..941dd7f 100644
--- a/docs/scripting.md
+++ b/docs/scripting.md
@@ -101,6 +101,12 @@ The status text appears in the pane's frame; the buttons are real targets in it.
 A program that wants to be asked something can ask *in place* rather than
 printing a prompt and hoping.
 
+With the tab bar [on a side](panes.md#the-tab-bar), the status is also a row
+under the pane's tab — visible from every other tab, and clicking it jumps to
+the pane that said it. A status is not decoration on your own frame; it is how
+a pane reports progress to somebody working elsewhere, which is a reason to
+keep it current and `clear` it when the work is done.
+
 `purpose` is the other verb: `printf '\033]5577;1;purpose;logs\033\\'`. A purpose
 declared by a layout or the control API wins and cannot be overwritten this way.