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

docs/terminal/ghostty.mdx

@@ -0,0 +1,67 @@
+---
+title: Ghostty
+description: Ghostty configuration and its herdr key sync.
+---
+
+GPU terminal emulator kept alongside kitty. Its bindings send the same herdr prefix bytes as the kitty herdr host.
+
+| | |
+| --- | --- |
+| Source | `dot_config/ghostty/config`, `dot_config/ghostty/config.ghostty`, `dot_config/ghostty/themes/` |
+| Target | `~/.config/ghostty/` |
+| Install | Not listed in `.chezmoidata/packages.yaml`; install separately |
+
+Ghostty reads both `config` and `config.ghostty`. `config` holds all settings; `config.ghostty` contains a single line, `theme = noctalia`, which selects the active theme.
+
+## Options
+
+| Option | Value |
+| --- | --- |
+| `font-family` / `font-size` | `Victor Mono NF` / `12.5` |
+| `background-opacity` / `background-blur` | `0.9` / `true` |
+| `window-decoration` | `false`; `gtk-titlebar = false` |
+| `window-padding-x/y` | `12` |
+| `cursor-style` | `underline`, blinking |
+| `scrollback-limit` | `3023` |
+| `mouse-hide-while-typing` | `true` |
+| `copy-on-select` | `false` |
+| `confirm-close-surface` | `false` |
+| `app-notifications` | `no-clipboard-copy,no-config-reload` |
+| `quit-after-last-window-closed` | `false`, delay `5m` |
+| `shell-integration` | `detect`, features `cursor,sudo,title,no-cursor` |
+| `gtk-single-instance` | `true` |
+
+## Keybindings
+
+| Key | Action |
+| --- | --- |
+| `cmd+c` / `cmd+v` | Copy / paste |
+| `cmd+n` | New window |
+| `ctrl+plus` / `ctrl+minus` / `ctrl+zero` | Font size +1 / -1 / reset |
+| `shift+enter` | Sends a literal newline |
+| `ctrl+shift+alt+,` | Reload config |
+
+### herdr sync
+
+Placed last so they override defaults. Each sends `ctrl+b` (`\x02`) followed by a key; see [herdr](/terminal/herdr).
+
+| Key | Sends |
+| --- | --- |
+| `ctrl+shift+n` | `prefix %` (split vertical) |
+| `ctrl+shift+t` | `prefix c` |
+| `ctrl+tab` / `ctrl+shift+tab` | `prefix n` / `prefix p` |
+| `ctrl+shift+f` | `prefix s` (workspace picker) |
+| `ctrl+shift+l` / `ctrl+shift+h` | `prefix .` / `prefix ,` (next / previous agent) |
+| `ctrl+shift+j` / `ctrl+shift+k` | `prefix j` / `prefix k` (next / previous workspace) |
+| `super+enter` | `prefix N` |
+| `super+r` | `prefix W` |
+| `ctrl+shift+r` | `prefix T` |
+| `ctrl+shift+,` | `prefix S` (herdr settings) |
+
+## Themes
+
+| Theme | Notes |
+| --- | --- |
+| `noctalia` | Active. Palette matching the Noctalia shell. |
+| `ii-auto` | Auto-generated by the ii wallpaper theming system; not meant to be edited. |
+| `koda-dark` / `koda-light` | Koda palettes with `bold-is-bright = true`. |

docs/terminal/herdr.mdx

@@ -0,0 +1,94 @@
+---
+title: herdr
+description: herdr, an agent-aware terminal multiplexer, with its keys, theme, plugins and Claude Code hook.
+---
+
+herdr is a terminal multiplexer with workspaces, tabs and panes, a sidebar, a prefix key (`ctrl+b`), and a plugin system. It tracks coding agents running in its panes: agent-state colors, next/previous agent keys, and an integration that reports Claude Code sessions to it.
+
+| | |
+| --- | --- |
+| Source | `dot_config/herdr/config.toml`, `dot_config/herdr/plugins.json`, `dot_config/herdr/plugins/config/`, `dot_config/herdr/empty_dot_plugins.lock`, `dot_config/herdr/kitty.conf`, `dot_config/herdr-nvim/config.toml` |
+| Target | `~/.config/herdr/`, `~/.config/herdr-nvim/config.toml` |
+| Install | Not in `packages.yaml`; updated by topgrade (`herdr update`) |
+| Launch | kitty `super+a` (see [kitty](/terminal/kitty)); Ghostty keys send the same prefix bytes |
+
+## config.toml
+
+`onboarding = false`.
+
+### UI and theme
+
+| Setting | Value |
+| --- | --- |
+| `ui.pane_borders`, `ui.pane_outer_borders` | `false` (panes separated by gaps only) |
+| `ui.prompt_new_tab_name` | `false` |
+| `ui.accent` | `#5ea1ff` |
+| `ui.status_indicators` | `symbols` |
+| `ui.toast.delivery` | `system` |
+| `theme.name` | `terminal`, `auto_switch = false` |
+| `theme.custom.panel_bg` | `reset` (keeps kitty's translucency and compositor blur) |
+| `sidebar_bg` / `active_row_bg` / `selection_bg` | `#16181a` / `#1e2124` / `#3c4048` |
+| `accent` / `surface_dim` | `#243348` / `#5ea1ff` (active tab plate matches kitty's tab bar) |
+| Agent-state colors | green `#5eff6c`, yellow `#f1ff5e`, red `#ff6e5e`, peach `#ffbd5e`, mauve `#bd5eff` |
+| `experimental.kitty_graphics` | `true`; `pane_history = false` |
+| `switch_ascii_input_source_in_prefix` | `true` |
+
+These are cyberdream colors.
+
+### Keys
+
+| Key | Action |
+| --- | --- |
+| `prefix %` | Split vertical |
+| `prefix "` | Split horizontal |
+| `prefix d` | Detach |
+| `prefix s` | Workspace picker |
+| `prefix shift+s` | Settings |
+| `k` / `j` | Move up / down in the workspace picker (pane up/down in navigate mode unbound) |
+| `prefix .` / `prefix ,` | Next / previous agent |
+| `prefix j` / `prefix k` | Next / previous workspace |
+| `prefix up/down/left/right` | Focus pane |
+| `ctrl+h/j/k/l` | `vim-herdr-navigation` left/down/up/right |
+| `prefix e` | `chmarax.herdr-nvim.toggle` (nvim sidebar) |
+| `prefix o` | `chmarax.herdr-nvim.pick-file` (open file from agent output) |
+| `prefix t` | `switchboard.menu` |
+| `prefix shift+p` | `switchboard.commands` |
+| `prefix shift+l` | `switchboard.git` |
+| `prefix shift+k` | `switchboard.projects` |
+| `prefix y` | Open `official.browser` plugin in a right split |
+| `prefix shift+o` | Open `official.browser` as an overlay |
+
+## Plugins
+
+`plugins.json` is herdr's plugin registry. `.plugins.lock` is created empty. `plugins/config/official.browser/` and `plugins/config/vim-herdr-navigation/` hold placeholder `.keep` files for per-plugin config.
+
+| Plugin | Description (from its manifest) |
+| --- | --- |
+| `chmarax.herdr-nvim` | Full-height nvim sidebar with agent annotations |
+| `herdr-automatic-rename` | Names tabs after the foreground program, adds 1–9 jump numbers |
+| `io.github.salemsayed.omaherd` | Tells the Omarchy bar when an agent changes state |
+| `official.browser` | Open and inspect real browser pages from herdr |
+| `oh-my-opencode-slim` | OpenCode agent orchestration with a herdr adapter |
+| `persiyanov.reviewr` | Review agent-written diffs beside the chat |
+| `rjyo.window-title-sync` | Syncs the outer terminal title to the focused workspace, tab and agent |
+| `switchboard` | Command palette: projects, commands, ports, git, clone, settings |
+| `vim-herdr-navigation` | Vim-aware `ctrl+h/j/k/l` pane movement |
+
+[fish](/shell/fish) sources `herdr-automatic-rename`'s `shell/hook.fish` if present.
+
+## herdr-nvim
+
+```toml ~/.config/herdr-nvim/config.toml
+[sidebar]
+position = "left"
+```
+
+The nvim sidebar opens to the left of existing panes (default is right).
+
+## Claude Code integration
+
+`dot_claude/hooks/executable_herdr-agent-state.sh` is installed and managed by herdr (integration id `claude`, version 7) and registered in `dot_claude/settings.json` with the `session` argument. It runs only inside herdr (`HERDR_ENV=1`, `HERDR_SOCKET_PATH`, `HERDR_PANE_ID` set), ignores subagent events, and sends a `pane.report_agent_session` JSON request over herdr's Unix socket with the pane id, Claude session id and transcript path. See [Claude Code](/ai/claude-code).
+
+## herdr/kitty.conf
+
+A legacy kitty config kept in the herdr folder. It runs `tmux new-session -A -s main`, listens on `unix:@mykitty`, includes `current-theme.conf`, maps `super`/`alt` keys to tmux prefix bytes, and has a copy of an older `tmux.conf` appended. The active herdr host is `~/.config/kitty/herdr.conf`.

docs/terminal/index.mdx

@@ -0,0 +1,22 @@
+---
+title: Terminal
+description: Terminal emulators and multiplexers configured by the dotfiles.
+sidebar:
+  label: Overview
+---
+
+kitty is the primary terminal. It runs in three modes: plain kitty (kitty owns splits and tabs), a tmux host, and a herdr host. Ghostty is kept as a secondary terminal whose bindings drive herdr the same way.
+
+| Page | Source | What it covers |
+| --- | --- | --- |
+| [kitty](/terminal/kitty) | `dot_config/kitty/` | Main config, host configs (tmux, herdr, goliath), kittens, custom tab bar |
+| [Ghostty](/terminal/ghostty) | `dot_config/ghostty/` | Config, herdr key sync, themes |
+| [tmux](/terminal/tmux) | `dot_config/tmux/` | Prefix, bindings, tpm plugins, dotbar status line, Niri titles |
+| [herdr](/terminal/herdr) | `dot_config/herdr/`, `dot_config/herdr-nvim/` | Agent-aware multiplexer: keys, theme, plugins, Claude hook |
+
+## Shared conventions
+
+- Font: VictorMono Nerd Font everywhere.
+- Background opacity `0.9`, no window decorations; the compositor provides blur.
+- Prefix `ctrl+b` in tmux and herdr. kitty and Ghostty translate chords into the prefix byte `\x02` plus a key, so the same physical shortcut works across hosts.
+- `ctrl+h/j/k/l` moves between panes across nvim, kitty, tmux, and herdr (vim-aware handoff at every layer).

docs/terminal/kitty.mdx

@@ -0,0 +1,195 @@
+---
+title: kitty
+description: kitty configuration, host variants, custom kittens and the Python tab bar.
+---
+
+GPU terminal emulator and the primary terminal on every role.
+
+| | |
+| --- | --- |
+| Source | `dot_config/kitty/` |
+| Target | `~/.config/kitty/` |
+| Install | `kitty` in `.chezmoidata/packages.yaml` (pacman on Arch, cask on macOS, plus `font-victor-mono-nerd-font` cask) |
+
+<FileTree>
+- dot_config/kitty/
+  - kitty.conf
+  - tmux.conf
+  - herdr.conf
+  - goliath.conf
+  - ssh.conf
+  - symlink_current-theme.conf
+  - tab_bar.py
+  - pass_keys.py
+  - navigate_kitty.py
+  - select_tab.py
+  - switchtab.py
+  - window_titler.py
+  - themes/
+    - cyberdream.conf
+    - koda-dark.conf
+    - koda-light.conf
+    - noctalia.conf
+</FileTree>
+
+`__pycache__/` next to `tab_bar.py` is excluded in `.chezmoiignore.tmpl`.
+
+## Theme and colors
+
+Every config ends with:
+
+```conf ~/.config/kitty/kitty.conf
+include ~/.local/state/omarchy/current/theme/kitty.conf
+```
+
+Colors come from the active Omarchy theme; it is included last so it wins. `symlink_current-theme.conf` creates `~/.config/kitty/current-theme.conf` as a symlink to `themes/noctalia.conf`. Only the legacy `dot_config/herdr/kitty.conf` includes `current-theme.conf`; the main config does not. `themes/` holds `cyberdream`, `koda-dark`, `koda-light` and `noctalia` color files.
+
+## kitty.conf
+
+| Option | Value |
+| --- | --- |
+| `font_family` | `VictorMono Nerd Font`, then overridden in the `BEGIN_KITTY_FONTS` block to `family="VictorMono Nerd Font Mono"`; bold/italic `auto` |
+| `window_padding_width` | `8` |
+| `hide_window_decorations` | `yes` |
+| `background_opacity` | `0.9` |
+| `cursor_trail` | `10`, `cursor_trail_start_threshold 0`, `cursor_trail_decay 0.01 0.05` |
+| `cursor_blink_interval` | `0` (set to 1, then overridden) |
+| `copy_on_select` | `auto` |
+| `strip_trailing_spaces` | `smart` |
+| `confirm_os_window_close` | `0` |
+| `allow_remote_control` | `socket-only` |
+| `listen_on` | `unix:@kitty-{kitty_pid}` |
+| `enabled_layouts` | `splits:split_axis=vertical,stack` |
+| Tab bar | `powerline`, `angled`, aligned left, top edge, `tab_title_template "{custom}"` |
+
+:::note
+Transparency uses kitty's own alpha, so text stays opaque. This alpha is also what lets the compositor blur the window: Hyprland enables blur globally and opts out every window except terminal classes.
+:::
+
+The socket also exports `KITTY_LISTEN_ON` into each pane. nvim reads it to know kitty owns the panes and hands `ctrl+h/j/k/l` back to kitty at an edge.
+
+### Launch aliases
+
+| Alias | Expands to |
+| --- | --- |
+| `launch_mn` | `launch --cwd=current --type=overlay-main` |
+| `launch_os` | `launch --cwd=current --type=os-window` |
+| `launch_ov` | `launch --cwd=current --type=overlay` |
+| `launch_tb` | `launch --cwd=current --type=tab` |
+| `launch_hs` | `launch --cwd=current --location=hsplit --bias=30` |
+| `launch_vs` | `launch --cwd=current --location=vsplit --bias=40` |
+| `launch_vs50` | `launch --cwd=current --location=vsplit --bias=50` |
+
+### Keybindings
+
+| Key | Action |
+| --- | --- |
+| `super+n` | Vertical split 50/50 (`launch_vs50`) |
+| `super+z` | Toggle `stack` layout (zoom) |
+| `ctrl+shift+t`, `super+enter` | New tab in current cwd |
+| `ctrl+space`, `ctrl+shift+j` | Horizontal split, 30% (`launch_hs`) |
+| `ctrl+enter`, `ctrl+shift+l` | Vertical split, 40% (`launch_vs`) |
+| `ctrl+shift+space` | New OS window |
+| `ctrl+shift+h` / `ctrl+shift+k` | Previous / next tab |
+| `ctrl+shift+g` | `lazygit` in an overlay |
+| `ctrl+shift+f` | `yazi` in a new tab |
+| `ctrl+shift+e` | `nvim` in a 50/50 vertical split |
+| `ctrl+shift+p` | `atuin-pick` in a horizontal split |
+| `super+t` | Spawn a separate kitty (`--class=kitty-tmux`, `--config ~/.config/kitty/tmux.conf`) |
+| `super+a` | Spawn a separate kitty (`--class=kitty-herdr`, `--config ~/.config/kitty/herdr.conf`) |
+| `ctrl+shift+c` / `ctrl+shift+v` | Copy / paste clipboard |
+| `alt+q w e r t y u i o` | Go to tab 1–9 |
+| `ctrl+h/j/k/l` | `pass_keys.py`: move to neighbor window left/bottom/top/right, or pass the key through |
+| `super+left` / `super+right` | Resize window narrower / wider |
+| `super+up` / `super+down` | Resize window taller / shorter (by 3) |
+
+The tmux and herdr hosts are separate kitty processes because `launch` cannot take `--config`.
+
+## Host configs
+
+### tmux.conf — kitty as a tmux host
+
+Launched by `super+t`. kitty stays a dumb terminal; tmux owns panes, windows and sessions. `listen_on unix:@kitty-tmux`, `tab_bar_style hidden`, `shell kitty-tmux` (a launcher script), and `clear_all_shortcuts yes`, so only the bindings below exist. Prefix byte `\x02` is `ctrl+b`; see [tmux](/terminal/tmux) for what each prefix key does.
+
+| Key | Sends / does |
+| --- | --- |
+| `ctrl+shift+c` / `ctrl+shift+v` | Copy / paste |
+| `ctrl+plus` / `ctrl+minus` / `ctrl+0` | Font size +1 / -1 / reset |
+| `ctrl+shift+alt+,` | Reload kitty config |
+| `ctrl+shift+a` | Spawn a kitty herdr host |
+| `super+t`, `super+enter`, `ctrl+shift+t` | `prefix t` (new window) |
+| `ctrl+shift+h` / `ctrl+shift+k` | `prefix H` / `prefix L` (previous / next window) |
+| `alt+q w e r t y u i o` | `prefix 1`–`9` |
+| `ctrl+shift+j` | `prefix "` (split below) |
+| `ctrl+shift+l`, `ctrl+enter` | `prefix %` (split right) |
+| `ctrl+shift+f` | `prefix z` (zoom) |
+| `ctrl+shift+w`, `super+w` | `prefix x` (kill pane) |
+| `super+left/right/up/down` | `prefix` + `ctrl+arrow` (resize) |
+| `ctrl+shift+g` | `tmux display-popup` 90%×90% running `lazygit` in pane cwd |
+| `ctrl+shift+e` | `tmux new-window` running `nvim` in pane cwd |
+| `ctrl+shift+p` | `tmux split-window -v -l 25%` running `atuin-pick` |
+| `super+n`, `ctrl+shift+space` | New OS window |
+| `super+d` | `prefix d` (detach) |
+
+### herdr.conf — kitty as a herdr host
+
+Launched by `super+a`. Class `kitty-herdr`, `tab_bar_style hidden` (herdr draws its own sidebar and tab strip), `shell herdr` (launches or attaches the persistent session; closing the window detaches). Base appearance matches `kitty.conf`, without a `listen_on`. Keys mirror the [Ghostty](/terminal/ghostty) config so both drive herdr identically; an uppercase letter after `\x02` is the shift variant. See [herdr](/terminal/herdr).
+
+| Key | Sends / does |
+| --- | --- |
+| `super+c` / `super+v` | Copy / paste |
+| `ctrl+plus` / `ctrl+minus` / `ctrl+0` | Font size +1 / -1 / reset |
+| `ctrl+shift+alt+,` | Reload kitty config |
+| `ctrl+shift+n` | `prefix N` |
+| `super+n` | `prefix G` |
+| `super+t`, `ctrl+shift+t` | `prefix c` |
+| `ctrl+space` | `prefix t` (Switchboard menu) |
+| `super+z` | `prefix z` |
+| `ctrl+tab` / `ctrl+shift+tab` | `prefix .` / `prefix ,` (next / previous agent) |
+| `ctrl+shift+f` | `prefix K` (Switchboard projects) |
+| `ctrl+shift+g` | `prefix L` (Switchboard git) |
+| `ctrl+shift+e` | `prefix e` (herdr-nvim sidebar toggle) |
+| `ctrl+shift+o` | `prefix o` (herdr-nvim pick file) |
+| `ctrl+shift+h` / `ctrl+shift+l` | `prefix p` / `prefix n` |
+| `ctrl+shift+j` / `ctrl+shift+k` | `prefix j` / `prefix k` (next / previous workspace) |
+| `ctrl+shift+w` | `prefix W` |
+| `ctrl+shift+r` | `prefix T` |
+| `ctrl+shift+,` | `prefix S` (herdr settings) |
+| `ctrl+shift+q` | `prefix x` |
+| `ctrl+shift+p` | `prefix P` (Switchboard commands) |
+
+### goliath.conf — remote tmux over mosh
+
+Opens straight into the tmux session `main` on host `goliath` via `mosh goliath -- tmux new-session -A -s main`. `font_size 9.0`, `listen_on unix:@kitty-goliath`, `env MOSH_TITLE_NOPREFIX=1` (drops mosh's `[mosh] ` title prefix), `tab_bar_style hidden`.
+
+:::warning
+mosh bootstraps ssh with `-S none`, so non-interactive key auth to goliath must work. It needs mosh on both ends and UDP 60000–61000 open. mosh sets `TERM=xterm-256color`, so kitty-only capabilities such as undercurl are unavailable inside.
+:::
+
+| Key | Sends |
+| --- | --- |
+| `super+w` | `prefix x` |
+| `super+t` | `prefix %` |
+| `super+n` | `prefix "` |
+| `super+enter`, `alt+n` | `prefix t` |
+| `alt+h` / `alt+l` | `prefix H` / `prefix L` |
+| `alt+q w e r t y u i o` | `prefix 1`–`9` (`alt+t` is bound twice; the later `prefix 5` wins) |
+| `super+left/right/up/down` | `prefix` + `ctrl+arrow` |
+| `super+d` | `prefix d` |
+
+### ssh.conf
+
+Kitten `ssh` config: for `hostname goliath`, `share_connections yes`.
+
+## Kittens and Python
+
+| File | Purpose |
+| --- | --- |
+| `tab_bar.py` | Provides `draw_title` for `{custom}` in the tab template. Title is `<index> <icon> <label>`: the label is the git repo root name of the tab's cwd (walks up for `.git`), or the file nvim is editing (parsed from nvim's title). Icon comes from the foreground process cmdline (editors, AI agents like claude/omp/opencode/codex, git tools, docker, herdr, tmux, yazi, btop, atuin, ssh, chezmoi, …) with a folder fallback. Labels are elided at 28 chars. No subprocesses or timers. |
+| `pass_keys.py` | Bound to `ctrl+h/j/k/l`. If the window's foreground process matches `vim`, `nvim`, `fzf`, `tmux` or `herdr`, the key is forwarded; otherwise kitty moves to the neighboring window. |
+| `navigate_kitty.py` | No-UI kitten that calls `neighboring_window` with a direction argument; the counterpart nvim can invoke. Not mapped in `kitty.conf`. |
+| `select_tab.py` | Full-screen fuzzy tab picker using `kitty @ ls` data; shows cwds zsh-style. Keys: Up/Down/PgUp/PgDn scroll, Enter selects, typing filters, `ctrl+c`/Esc quits. Not mapped in `kitty.conf`. |
+| `switchtab.py` | Focuses the tab whose `vt` user var matches the argument, or launches one with that var and reorders tabs by `vt`. Not mapped. |
+| `window_titler.py` | Watcher that appends `[<vt> <pty>]` to window titles. Not referenced in `kitty.conf`. |
+
+Related: the [tmux](/terminal/tmux) `is_vim` check and herdr's `vim-herdr-navigation` plugin complete the `ctrl+h/j/k/l` chain. Niri window rules match the `kitty`, `kitty-tmux` and `kitty-herdr` app-ids ([Niri](/desktop/niri)).

docs/terminal/meta.ts

@@ -0,0 +1,2 @@
+import { defineMeta } from "blume";
+export default defineMeta({ title: "Terminal", icon: "square-terminal", pages: ["index", "kitty", "ghostty", "tmux", "herdr"] });

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)`.