sl0ppty: a README you can read, and docs/ for the rest

The README was 331 lines and had become a manual with a title. Everything
in it was true and most of it was the wrong thing to hand somebody who
has just arrived: five pages of shader expression semantics before they
have split a pane.

So the front page is 60 lines -- what it is, install, run, where the docs
are, and six bullets on what is actually different about it -- and the
detail moved into docs/, nine pages that each answer one question:

    index.md      what it is, install, run, where to go
    keys.md       the leader, every default, rebinding, direct binds
    panes.md      splitting, resizing, the mouse, dead panes, small terminals
    config.md     the file, live reload, include, themes, the knobs
    shaders.md    the passes, the built-ins, the expression language
    chrome.md     where="chrome", channel, since, the perimeter trick
    layouts.md    a session as a file, and writing one back out
    scripting.md  the control socket, OSC 5577, headless
    design.md     the two decisions, and a map of the source

docs/nav holds the order and the grouping and nothing else -- titles come
from each page's own heading, so a renamed page cannot end up with two
names. It is what the site generator will read.

Reference material that only existed in code comments is written down for
the first time: every action that can be bound (including the two with no
default key, which is what the palette is for), every control verb, the
built-in shaders with what each takes, the pane-state ranking, and the
layout file's shape.

Two things I got wrong on the first pass and fixed before committing: the
docs linked repo files through github.com URLs for a project whose remote
is a private git server, so those are inline paths now; and the README
advertised `make docs`, which does not exist yet. It will in the next
commit, and it can be advertised then.

1 files changed, 93 insertions, 0 deletions

diff --git a/docs/panes.md b/docs/panes.md
new file mode 100644
index 0000000..388de89
--- /dev/null
+++ b/docs/panes.md
@@ -0,0 +1,93 @@
+# Panes and tabs
+
+A tab is a tree of splits. Panes keep running in every tab; only the one you are
+looking at is drawn.
+
+## Arranging
+
+- **Split** with `C-a \` and `C-a -`. Splitting the same direction again gives
+  three equal shares rather than 1/2 + 1/4 + 1/4.
+- **Resize** with `C-a H J K L`: the boundary moves the way you press, whichever
+  side of it you are on. Sizes are *weights*, so a resized layout survives the
+  window changing size.
+- **`C-a =`** gives every visible pane an even share again — each split divided
+  between the panes behind it, so one pane beside a stack of three is a quarter
+  of the width rather than half of it.
+- **`C-a Space`** turns the whole tab a quarter turn clockwise. Every split
+  changes axis and a row split's children reverse, because the pane on top of a
+  stack is the pane on the right once you turn it. Four turns come back exactly.
+  A turn that would squeeze a pane under the floor is refused with a word.
+- **`C-a z`** fills the tab with one pane and back; **`C-a m`** puts one away
+  into a strip along the bottom, still running. Click its row to bring it back.
+
+## The mouse
+
+Every mouse verb starts from the same list of rects the drawing filled in, so
+nothing you click can disagree with what is on screen.
+
+- **Click a pane's border to split toward it** — the side you click is the side
+  the new pane appears on. Resting there first shows a dashed line where the
+  split would land.
+- **Drag the gap between panes** to move that boundary. Where two gaps cross,
+  drag the crossing to move both at once.
+- **Drag a pane by its title** onto another to swap them. Everything it could
+  land on greys out; the pane in your hand keeps its colour.
+- **Double-click a name to rename it in place** — a pane's title or a tab in the
+  strip. Enter keeps it, Escape abandons it, empty gives it back to the program.
+- **Drag a tab along the strip** to reorder it. The strip rearranges as you go
+  rather than dropping it at the end.
+- 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.
+- Hovering anything says what it does, in a word, in the status line.
+
+## Finding a pane
+
+Tabs stop being navigation somewhere around six projects. `C-a f` opens a picker
+over the whole session — every tab, including panes a small window has collapsed
+out of sight. Type to narrow it by pane title, tab name or
+[purpose](layouts.md#purposes); arrows, `C-n`/`C-p` or tab to move; enter to go.
+A dot marks where you already are.
+
+## Panes that were given a command
+
+Split off a shell, do something, type `exit`: it closes, like a terminal should.
+But a pane that was *told to run something* — from a [layout](layouts.md) or the
+[control API](scripting.md) — keeps what it printed when that something exits,
+with a line saying how it ended and two buttons:
+
+```
+╰ exited: status 3 ───────────────────────────────[re-run]─[close]─╯
+```
+
+`[re-run]` (or `C-a r`) runs the same command again in the same pane, keeping
+the previous run above it in the scrollback. So a command that failed while you
+were looking elsewhere still has its error message when you get back, and a
+mistyped command in a fresh session no longer closes the session.
+
+Which panes stay is one setting, `keep_dead`: `commands` (the default), `all`,
+or `none`.
+
+## Small terminals
+
+When the panes no longer fit, the tab becomes a list of one-line headers with
+the focused pane open below them — and returns to exactly the layout you had
+when there is room again. Nothing is stored and restored: the arrangement is
+recomputed from the tree every frame, and the list is what that function returns
+when the room runs out.
+
+`min_pane` is where that starts happening; `min_split` is the smaller pane a
+split is willing to *create*.
+
+## Text, images, bells
+
+- **Select text to copy it.** Release the mouse and it is on your clipboard,
+  sent to your terminal over ssh as well as locally. Middle click pastes.
+- **Images work.** Kitty graphics pass through to your terminal, including the
+  half of the protocol other multiplexers drop, where a program uploads an image
+  once and places it every frame. Your terminal's cell size is carried through to
+  each pane, so a program can size an image without saying how many cells to
+  cover. PNG uploads are decoded here, because the terminal core ships no image
+  decoder. (Sixel is not supported.)
+- **A pane that beeps says so** — in its title, in its tab, and until you look at
+  it. `bell_indicator false` makes a bell silent *and* invisible, which is a real
+  choice. A [chrome shader](chrome.md) can make it louder.