Document usage, keybindings, TABBED_LOG/dump semantics; fix F8->F9/F10 comment

README.md

@@ -62,4 +62,63 @@ tabbed-wlroots <prog> [prog...]
 ```
 
 Each `<prog>` is one shell command; quote it when it takes arguments, e.g.
-`tabbed-wlroots "foot -e htop" "firefox -no-remote"`.
+`tabbed-wlroots "foot -e htop" "firefox -no-remote"`.
+
+Every argument starts a new tab. There is no tab-count limit. Client apps run
+as children of tabbed-wlroots and connect to its private Wayland socket, so
+`DISPLAY` is unset for them and their `WAYLAND_DISPLAY` points at the tabbed
+compositor (clients are launched with the GDK and Qt Wayland backends forced).
+
+Notes:
+- An argument written bare (starting with `-`) is taken as a tab launcher too
+  (unless quoted); a warning is printed when it looks like a stray option.
+- Without any arguments a usage message is printed and the program exits.
+- The client applications run inside the session, so closing their windows
+  only closes their tab; closing the host tabbed-wlroots window, or sending
+  SIGINT/SIGTERM, shuts the whole session down and kills all client children.
+
+## Key bindings
+
+| Key                        | Action                                            |
+|----------------------------|---------------------------------------------------|
+| `Ctrl+PageUp`              | Previous tab (hold to keep cycling)               |
+| `Ctrl+PageDown`            | Next tab (hold to keep cycling)                   |
+| `F11`                      | Toggle the host window fullscreen                 |
+| `F9`                       | Dump composed scene buffer to `/tmp/scene_N.ppm`  |
+| `F10`                      | Dump host back buffer to `/tmp/host_N.ppm`        |
+
+The tab-cycling hotkey only emits a physical press for the first tab switch;
+repeats are synthesized, so holding `Ctrl+PageUp/PageDown` keeps stepping
+through tabs while any other key stops it.
+
+## Logging (`TABBED_LOG`)
+
+Quiet by default: a plain launch prints nothing to the launching terminal
+except fatal errors. Set `TABBED_LOG` before starting:
+
+| Value | Meaning                                                          |
+|-------|------------------------------------------------------------------|
+| unset/`0` | Quiet. Only fatal errors are shown.                          |
+| `1`       | Info. Status lines, dump summaries, host notes (e.g. socket). |
+| `2`       | Debug. Adds a per-frame `[diag]` trace and EGL/render/import messages, and client stdout/stderr flows through. |
+
+At debug level (`2`) client programs also inherit the launching terminal's
+stdout/stderr instead of being silenced, which makes client errors visible.
+
+## Frame dumps (F9 / F10 / SIGUSR1 / TABBED_AUTODUMP)
+
+The frame-dump keys, `SIGUSR1`, and `TABBED_AUTODUMP` all write raw `P6`
+portable-pixmap files to `/tmp` regardless of the log level:
+
+- `F9` or `SIGUSR1` writes `/tmp/scene_N.ppm` — the composed scene (whatever
+  tabbed-wlroots rendered for the host).
+- `F10` or `SIGUSR1` writes `/tmp/host_N.ppm` — the host compositor's back
+  buffer, so you can see what the host actually displayed.
+- `N` is an incrementing per-run counter; a single `SIGUSR1` produces a
+  matching scene/host pair.
+- With `TABBED_AUTODUMP` (any value, e.g. `TABBED_AUTODUMP=1`), a scene and
+  host dump are taken automatically once the first frame in which a client
+  committed a CPU-readable (shared-memory) buffer — handy for capturing
+  exactly what a newly launched client drew.
+- At `TABBED_LOG=2` the diagnostic that detects the client's own shm buffer
+  additionally writes that buffer to `/tmp/client_N.ppm`.