docs: add comprehensive documentation for AI agents, chezmoi workflow, shell setup, desktop configuration, terminal multiplexers, and developer tools

docs/terminal/tmux.mdx

@@ -0,0 +1,95 @@
+---
+title: tmux
+description: tmux prefix, options, bindings, tpm plugins and the dotbar status line.
+---
+
+Terminal multiplexer. Used locally through the kitty tmux host (`super+t` in [kitty](/terminal/kitty)) and remotely on goliath.
+
+| | |
+| --- | --- |
+| Source | `dot_config/tmux/tmux.conf`, `dot_config/tmux/tmux-nerd-font-window-name.yml`, `dot_config/tmux/executable_niri-title.sh` |
+| Target | `~/.config/tmux/` |
+| Install | `tmux` in `.chezmoidata/packages.yaml` (pacman, brew) |
+
+tpm is cloned to `~/.config/tmux/plugins/tpm` by `.chezmoiscripts/run_onchange_after_40-post.sh.tmpl` when tmux exists and the directory is missing. `.config/tmux/plugins/**` is ignored by chezmoi. Install plugins with `prefix I`.
+
+:::note
+`tmux.conf` ends with `run '~/.tmux/plugins/tpm/tpm'`, while the script clones to `~/.config/tmux/plugins/tpm`.
+:::
+
+## Options
+
+The prefix is the default `ctrl+b`.
+
+| Option | Value |
+| --- | --- |
+| `default-terminal` | `tmux-256color`; `xterm-kitty:Tc` override; features `RGB:usstyle:hyperlinks:clipboard:extkeys` |
+| `extended-keys` | `always`, format `csi-u` |
+| `base-index` / `pane-base-index` | `1` / `1`; `renumber-windows on` |
+| `status-position` | `top` |
+| `allow-passthrough` | `on` (kitty graphics for yazi previews); `TERM`, `TERM_PROGRAM` added to `update-environment` |
+| `set-clipboard` | `on` (OSC 52) |
+| `mouse` | `on` |
+| `mode-keys` | `vi` |
+| `set-titles` | `on`, `set-titles-string "#T (#S)"`, `status-interval 1`, `automatic-rename on` |
+| `history-limit` | `50000` |
+| Styling | `status-style` and `popup-style` use default bg; popup border rounded, `fg=#5c5c66` |
+
+## Keybindings
+
+| Key | Action |
+| --- | --- |
+| `S-Enter` (no prefix) | Sends `Esc [13;2u` |
+| `prefix t` | New window in pane cwd; on sessions with `@ssh_host` set (by the Vicinae tmux-sessions extension), runs `ssh <host>` instead |
+| `prefix [` / `prefix H` | Previous window |
+| `prefix ]` / `prefix L` | Next window |
+| `prefix %` | Split right, 30% width, pane cwd |
+| `prefix "` | Split below, 25% height, pane cwd |
+| `prefix Escape` | Copy mode |
+| `ctrl+h/j/k/l` (no prefix) | Select pane left/down/up/right, or forward the key if the pane runs vim/nvim/fzf (`is_vim`) |
+| `prefix ctrl+l` | Send `ctrl+l` (clear screen) |
+| `prefix o` | tmux-sessionx picker (`@sessionx-bind`) |
+| `C-Space` (no prefix) | tmux-palette |
+| `M-f` / `M-m` | tmux-palette find pane / move pane |
+
+### Copy mode (vi)
+
+| Key | Action |
+| --- | --- |
+| `v` | Begin selection |
+| `y` | Copy to `wl-copy` and exit |
+| `Y` | Copy to `wl-copy` and cancel |
+| Mouse drag end | Copy to `wl-copy` |
+| `ctrl+h/j/k/l` | Select pane |
+
+## Plugins
+
+| Plugin | Settings |
+| --- | --- |
+| `tmux-plugins/tpm` | Plugin manager |
+| `tmux-plugins/tmux-sensible` | Defaults |
+| `vaaleyard/tmux-dotbar` | Status line, see below |
+| `tmux-plugins/tmux-resurrect` | nvim strategy `session`, captures pane contents, restores `ssh psql mysql sqlite3 purple lazygit lazydocker opencode` and `claude` as `claude --continue` |
+| `joshmedeski/tmux-nerd-font-window-name` | Icons from `tmux-nerd-font-window-name.yml` |
+| `omerxx/tmux-sessionx` | Bound to `o`, zoxide mode on, transparent fzf colors |
+| `tmux-plugins/tmux-continuum` | Save every 10 min; auto-restore `off` (the `kitty-tmux` launcher restores) |
+| `eduwass/tmux-palette` | Command palette |
+
+### Status line (dotbar)
+
+Top, rounded, centered (`absolute-centre`), left section on, right off, session on the left. Colors: bg `#0B0E14`, fg `#475266`, current `#BFBDB6`, session `#565B66`, prefix `#95E6CB`. Window format ` #W ` separated by ` • `; right text ` %H:%M `. Bold off. SSH indicator enabled with an icon; maximized icon only on the zoomed tab.
+
+## tmux-nerd-font-window-name.yml
+
+`show-name: true`, icon on the left, a fallback icon, blank multi-pane icon. Icons are defined for `mprocs`, `mm`, `macmon`, `make`, `zsh`, `nvim`, `devbox`, `psql`, `yazi`, `lazygit`, `gh`, `tv`, `docker`, `bun`, `node`, `npm`, `pnpm`, `go`, `bunx`, `claude`.
+
+## niri-title.sh
+
+Installed only on Linux `desktop`/`laptop` roles (gated in `.chezmoiignore.tmpl`). Given the pane command, path, tty and title, it prints a context segment for the window title read by [Niri](/desktop/niri), by priority:
+
+1. `ssh`/`mosh-client`/`autossh`/`et`: the remote target.
+2. `nvim`/`vim`: the pane title (current file).
+3. Git repo: directory name and branch.
+4. Otherwise the cwd basename.
+
+`tmux.conf` does not currently call the script; its title string is `#T (#S)`.