chore(docs): regenerate manual and man page

docs/fish-config.1

@@ -1,3 +1,4 @@
+'\" t
 .\" Automatically generated by Pandoc 3.1.3
 .\"
 .\" Define V font for inline verbatim, using C font in formats
@@ -182,172 +183,325 @@ These variables are exported from config.fish on every interactive
 session.
 Override them in local.fish (see Section 10, Personalization).
 .SS Environment Directories (XDG)
-.IP
+.PP
-.nf
+.TS
-\f[C]
+tab(@);
-XDG_CONFIG_HOME    \[ti]/.config
+l l.
-XDG_CACHE_HOME     \[ti]/.cache
+T{
-XDG_DATA_HOME      \[ti]/.local/share
+Variable
-XDG_STATE_HOME     \[ti]/.local/state
+T}@T{
-\f[R]
+Value
-.fi
+T}
+_
+T{
+\f[V]XDG_CONFIG_HOME\f[R]
+T}@T{
+\f[V]\[ti]/.config\f[R]
+T}
+T{
+\f[V]XDG_CACHE_HOME\f[R]
+T}@T{
+\f[V]\[ti]/.cache\f[R]
+T}
+T{
+\f[V]XDG_DATA_HOME\f[R]
+T}@T{
+\f[V]\[ti]/.local/share\f[R]
+T}
+T{
+\f[V]XDG_STATE_HOME\f[R]
+T}@T{
+\f[V]\[ti]/.local/state\f[R]
+T}
+.TE
 .PP
 Tools that respect XDG are directed to these paths rather than polluting
 $HOME.
 .SS Tool Homes (XDG-compliant)
-.IP
+.PP
-.nf
+.TS
-\f[C]
+tab(@);
-CARGO_HOME         $XDG_DATA_HOME/cargo
+l l.
-RUSTUP_HOME        $XDG_DATA_HOME/rustup
+T{
-GOPATH             $XDG_DATA_HOME/go
+Variable
-BUN_INSTALL        $XDG_DATA_HOME/bun
+T}@T{
-NPM_CONFIG_PREFIX  $XDG_DATA_HOME/npm-global
+Value
-GNUPGHOME          $XDG_CONFIG_HOME/gnupg
+T}
-WAKATIME_HOME      $XDG_CONFIG_HOME/wakatime
+_
-\f[R]
+T{
-.fi
+\f[V]CARGO_HOME\f[R]
+T}@T{
+\f[V]$XDG_DATA_HOME/cargo\f[R]
+T}
+T{
+\f[V]RUSTUP_HOME\f[R]
+T}@T{
+\f[V]$XDG_DATA_HOME/rustup\f[R]
+T}
+T{
+\f[V]GOPATH\f[R]
+T}@T{
+\f[V]$XDG_DATA_HOME/go\f[R]
+T}
+T{
+\f[V]BUN_INSTALL\f[R]
+T}@T{
+\f[V]$XDG_DATA_HOME/bun\f[R]
+T}
+T{
+\f[V]NPM_CONFIG_PREFIX\f[R]
+T}@T{
+\f[V]$XDG_DATA_HOME/npm-global\f[R]
+T}
+T{
+\f[V]GNUPGHOME\f[R]
+T}@T{
+\f[V]$XDG_CONFIG_HOME/gnupg\f[R]
+T}
+T{
+\f[V]WAKATIME_HOME\f[R]
+T}@T{
+\f[V]$XDG_CONFIG_HOME/wakatime\f[R]
+T}
+.TE
 .SS Editor and Pager
-.IP
+.PP
-.nf
+.TS
-\f[C]
+tab(@);
-EDITOR      nvim (falls back to vi if nvim is absent)
+lw(35.0n) lw(35.0n).
-VISUAL      unset by default; set a GUI editor via local.fish (the edit
+T{
-            function falls back to a GUI chain when VISUAL is empty)
+Variable
-SUDO_EDITOR same as EDITOR
+T}@T{
-PAGER       ov (falls back to less)
+Value / Notes
-\f[R]
+T}
-.fi
+_
+T{
+\f[V]EDITOR\f[R]
+T}@T{
+\f[V]nvim\f[R] (falls back to \f[V]vi\f[R] if \f[V]nvim\f[R] is absent)
+T}
+T{
+\f[V]VISUAL\f[R]
+T}@T{
+unset by default; set a GUI editor via \f[V]local.fish\f[R] (the
+\f[V]edit\f[R] function falls back to a GUI chain when \f[V]VISUAL\f[R]
+is empty)
+T}
+T{
+\f[V]SUDO_EDITOR\f[R]
+T}@T{
+same as \f[V]EDITOR\f[R]
+T}
+T{
+\f[V]PAGER\f[R]
+T}@T{
+\f[V]ov\f[R] (falls back to \f[V]less\f[R])
+T}
+.TE
 .SS Scrollback History
-.IP
-.nf
-\f[C]
-__fish_scrollback_history_dir        (unset → \[ti]/.terminal_history)
-__fish_scrollback_history_max_files  (unset → 100)
-SCROLLBACK_HISTORY_DIR        \[ti]/.terminal_history    (exported mirror)
-SCROLLBACK_HISTORY_MAX_FILES  100                    (exported mirror)
-\f[R]
-.fi
 .PP
-The __fish_scrollback_history_* universal variables are the fish-style
+.TS
-source of truth \[em] set them via \f[V]config-settings\f[R] → Paths, or
+tab(@);
-\f[V]set -U\f[R] directly.
+l l.
-config.fish exports the SCROLLBACK_HISTORY_* mirrors from them, because
+T{
-the POSIX wrapper scripts (paru/yay/tmux/zellij logging and
+Variable
-_prune_terminal_logs) read the exported names from the environment.
+T}@T{
-When the __fish_ vars are unset, the documented defaults are exported.
+Value / Notes
-config.fish deliberately does not create a global source var, which
+T}
-would shadow the universal and stop live edits from taking effect.
+_
+T{
+\f[V]__fish_scrollback_history_dir\f[R]
+T}@T{
+(unset → \f[V]\[ti]/.terminal_history\f[R])
+T}
+T{
+\f[V]__fish_scrollback_history_max_files\f[R]
+T}@T{
+(unset → \f[V]100\f[R])
+T}
+T{
+\f[V]SCROLLBACK_HISTORY_DIR\f[R]
+T}@T{
+\f[V]\[ti]/.terminal_history\f[R] (exported mirror)
+T}
+T{
+\f[V]SCROLLBACK_HISTORY_MAX_FILES\f[R]
+T}@T{
+\f[V]100\f[R] (exported mirror)
+T}
+.TE
 .PP
-Scrollback logs accumulate in SCROLLBACK_HISTORY_DIR as timestamped
+The \f[V]__fish_scrollback_history_*\f[R] universal variables are the
-files.
+fish-style source of truth \[em] set them via \f[V]config-settings\f[R]
-When the count exceeds SCROLLBACK_HISTORY_MAX_FILES the oldest are
+→ Paths, or \f[V]set -U\f[R] directly.
-pruned automatically on exit.
+\f[V]config.fish\f[R] exports the \f[V]SCROLLBACK_HISTORY_*\f[R] mirrors
+from them, because the POSIX wrapper scripts
+(\f[V]paru\f[R]/\f[V]yay\f[R]/\f[V]tmux\f[R]/\f[V]zellij\f[R] logging
+and \f[V]_prune_terminal_logs\f[R]) read the exported names from the
+environment.
+When the \f[V]__fish_\f[R] vars are unset, the documented defaults are
+exported.
+\f[V]config.fish\f[R] deliberately does not create a global source var,
+which would shadow the universal and stop live edits from taking effect.
+.PP
+Scrollback logs accumulate in \f[V]SCROLLBACK_HISTORY_DIR\f[R] as
+timestamped files.
+When the count exceeds \f[V]SCROLLBACK_HISTORY_MAX_FILES\f[R] the oldest
+are pruned automatically on exit.
 Use \f[V]logs\f[R] to browse them interactively.
 .SS Other
-.IP
-.nf
-\f[C]
-GPG_TTY              $(tty)  \[em] ensures GPG passphrase prompts work
-CLAUDE_CODE_NO_FLICKER  1    \[em] suppress terminal flicker in Claude Code
-CDPATH               . \[ti]/projects \[ti]
-\f[R]
-.fi
 .PP
-Opinionated defaults (CDPATH, PAGER/MANPAGER, Vi mode, command shadows,
+.TS
-terminal integrations) can be switched off per category with universal
+tab(@);
-variables \[em] see Section 7, \[lq]Opinionated Components (Minimal
+lw(23.3n) lw(23.3n) lw(23.3n).
-Mode)\[rq].
+T{
+Variable
+T}@T{
+Value
+T}@T{
+Notes
+T}
+_
+T{
+\f[V]GPG_TTY\f[R]
+T}@T{
+\f[V]$(tty)\f[R]
+T}@T{
+ensures GPG passphrase prompts work
+T}
+T{
+\f[V]CLAUDE_CODE_NO_FLICKER\f[R]
+T}@T{
+\f[V]1\f[R]
+T}@T{
+suppress terminal flicker in Claude Code
+T}
+T{
+\f[V]CDPATH\f[R]
+T}@T{
+\f[V]. \[ti]/projects \[ti]\f[R]
+T}@T{
+T}
+.TE
+.PP
+Opinionated defaults (\f[V]CDPATH\f[R],
+\f[V]PAGER\f[R]/\f[V]MANPAGER\f[R], Vi mode, command shadows, terminal
+integrations) can be switched off per category with universal variables
+\[em] see Section 7, \[lq]Opinionated Components (Minimal Mode)\[rq].
 .SS Pager Hierarchy
 .PP
-$PAGER is set to ov when available, falling back to less.
+\f[V]$PAGER\f[R] is set to \f[V]ov\f[R] when available, falling back to
-The less wrapper function extends this into a full chain so anything
+\f[V]less\f[R].
-that calls less directly also benefits:
+The \f[V]less\f[R] wrapper function extends this into a full chain so
-.IP
+anything that calls \f[V]less\f[R] directly also benefits:
-.nf
-\f[C]
-$PAGER → ov → less → more → cat
-\f[R]
-.fi
 .PP
-When bat is installed, man pages are rendered with syntax highlighting:
+\f[V]$PAGER\f[R] → \f[V]ov\f[R] → \f[V]less\f[R] → \f[V]more\f[R] →
-.IP
+\f[V]cat\f[R]
-.nf
+.PP
-\f[C]
+When \f[V]bat\f[R] is installed, man pages are rendered with syntax
-MANROFFOPT   -c
+highlighting:
-MANPAGER     sh -c \[aq]col -bx | bat -l man -p\[aq]
+.PP
-\f[R]
+.TS
-.fi
+tab(@);
+l l.
+T{
+Variable
+T}@T{
+Value
+T}
+_
+T{
+\f[V]MANROFFOPT\f[R]
+T}@T{
+\f[V]-c\f[R]
+T}
+T{
+\f[V]MANPAGER\f[R]
+T}@T{
+\f[V]sh -c \[aq]col -bx \[rs]| bat -l man -p\[aq]\f[R]
+T}
+.TE
 .SS Integrations
 .SS Zoxide
 .PP
-cd, z, and cdi/zi are all mapped to zoxide-backed navigation.
+\f[V]cd\f[R], \f[V]z\f[R], and \f[V]cdi\f[R]/\f[V]zi\f[R] are all mapped
-Tab completions for cd and z blend standard directory entries (CWD and
+to \f[V]zoxide\f[R]-backed navigation.
-CDPATH) with frecency results so both familiar and frequently-visited
+Tab completions for \f[V]cd\f[R] and \f[V]z\f[R] blend standard
-paths appear in one list.
+directory entries (CWD and \f[V]CDPATH\f[R]) with frecency results so
+both familiar and frequently-visited paths appear in one list.
 .SS DirEnv
 .PP
-Automatically loads .envrc files on directory change.
+Automatically loads \f[V].envrc\f[R] files on directory change.
 Takes priority over the auto-venv logic \[em] if a directory is managed
-by direnv, the auto-venv activation is skipped entirely.
+by \f[V]direnv\f[R], the auto-venv activation is skipped entirely.
 .SS Auto Python Venv
 .PP
-When entering a directory that contains a .venv/, the virtualenv is
+When entering a directory that contains a \f[V].venv/\f[R], the
-activated automatically and deactivated when you leave the project tree.
+virtualenv is activated automatically and deactivated when you leave the
+project tree.
 .SS WakaTime
 .PP
 Every shell command is reported to WakaTime for time-tracking.
-Set FISH_WAKATIME_DISABLED=1 to disable without removing the plugin.
+Set \f[V]FISH_WAKATIME_DISABLED=1\f[R] to disable without removing the
+plugin.
 .SS Tailscale
 .PP
-Full tab completion for the tailscale CLI is provided via
+Full tab completion for the \f[V]tailscale\f[R] CLI is provided via
-conf.d/tailscale.fish.
+\f[V]conf.d/tailscale.fish\f[R].
 .SS Done Notifications
 .PP
 Desktop notifications fire when a command takes longer than 10 seconds
 and the terminal window is not focused.
 Configured via fish universal variables:
-.IP
+.PP
-.nf
+.TS
-\f[C]
+tab(@);
-__done_min_cmd_duration          10000 ms
+l l.
-__done_notification_urgency_level  low
+T{
-\f[R]
+Variable
-.fi
+T}@T{
+Value
+T}
+_
+T{
+\f[V]__done_min_cmd_duration\f[R]
+T}@T{
+\f[V]10000\f[R] ms
+T}
+T{
+\f[V]__done_notification_urgency_level\f[R]
+T}@T{
+\f[V]low\f[R]
+T}
+.TE
 .SS Scrollback History
 .PP
-When running inside Kitty, closing a shell session via exit saves a
+When running inside Kitty, closing a shell session via \f[V]exit\f[R]
-timestamped scrollback snapshot to SCROLLBACK_HISTORY_DIR.
+saves a timestamped scrollback snapshot to
+\f[V]SCROLLBACK_HISTORY_DIR\f[R].
 Files are named:
-.IP
-.nf
-\f[C]
-scrollback_YYYY-MM-DD_HH-MM-SS.log
-\f[R]
-.fi
 .PP
-The paru and yay wrappers (auto-generated in \[ti]/.local/bin/) run the
+\f[V]scrollback_YYYY-MM-DD_HH-MM-SS.log\f[R]
-command inside a PTY via script(1) so download progress bars are
+.PP
-preserved on screen, then render the captured terminal animation down to
+The \f[V]paru\f[R] and \f[V]yay\f[R] wrappers (auto-generated in
-a clean static log via scripts/clean_progress_log.py (a small
+\f[V]\[ti]/.local/bin/\f[R]) run the command inside a PTY via
-terminal-screen emulator that replays cursor movements, collapses
+\f[V]script(1)\f[R] so download progress bars are preserved on screen,
-repainted progress frames to their final state, and preserves ANSI
+then render the captured terminal animation down to a clean static log
-color).
+via \f[V]scripts/clean_progress_log.py\f[R] (a small terminal-screen
-If python3 is unavailable the wrapper falls back to dropping only the
+emulator that replays cursor movements, collapses repainted progress
-script(1) header/footer.
+frames to their final state, and preserves ANSI color).
+If \f[V]python3\f[R] is unavailable the wrapper falls back to dropping
+only the \f[V]script(1)\f[R] header/footer.
 Output is saved to:
-.IP
+.IP \[bu] 2
-.nf
+\f[V]paru_YYYY-MM-DD_HH-MM-SS.log\f[R]
-\f[C]
+.IP \[bu] 2
-paru_YYYY-MM-DD_HH-MM-SS.log
+\f[V]yay_YYYY-MM-DD_HH-MM-SS.log\f[R]
-yay_YYYY-MM-DD_HH-MM-SS.log
-\f[R]
-.fi
 .PP
-Before pruning, _scrollback_prune_junk silently removes empty files,
+Before pruning, \f[V]_scrollback_prune_junk\f[R] silently removes empty
-files with only a single meaningful line (e.g.\ bare [exited] captures),
+files, files with only a single meaningful line (e.g.\ bare
-and Kitty tab-rename prompt captures.
+\f[V][exited]\f[R] captures), and Kitty tab-rename prompt captures.
-Use exit \[en]no-log (or exit -n) to skip capture.
+Use \f[V]exit --no-log\f[R] (or \f[V]exit -n\f[R]) to skip capture.
 .PP
    *   *   *   *   *
 .SH 2. PATH SETUP
@@ -2846,79 +3000,236 @@ fish-deps manages these tools.
 Run \f[V]fish-deps\f[R] to check status, or \f[V]fish-deps install\f[R]
 to install missing ones.
 .SS Required
-.IP
+.PP
-.nf
+.TS
-\f[C]
+tab(@);
-fish      Fish shell >= 4.0
+l l.
-fzf       Fuzzy finder
+T{
-zoxide    Smart cd with frecency
+Tool
-\f[R]
+T}@T{
-.fi
+Description
+T}
+_
+T{
+\f[V]fish\f[R]
+T}@T{
+Fish shell >= 4.0
+T}
+T{
+\f[V]fzf\f[R]
+T}@T{
+Fuzzy finder
+T}
+T{
+\f[V]zoxide\f[R]
+T}@T{
+Smart cd with frecency
+T}
+.TE
 .SS Integrations
-.IP
+.PP
-.nf
+.TS
-\f[C]
+tab(@);
-wakatime   Developer time tracking
+l l.
-tailscale  Mesh VPN client
+T{
-\f[R]
+Tool
-.fi
+T}@T{
+Description
+T}
+_
+T{
+\f[V]wakatime\f[R]
+T}@T{
+Developer time tracking
+T}
+T{
+\f[V]tailscale\f[R]
+T}@T{
+Mesh VPN client
+T}
+.TE
 .SS Recommended
-.IP
+.PP
-.nf
+.TS
-\f[C]
+tab(@);
-cargo       Rust toolchain (via rustup); used by fish-deps to install
+lw(35.0n) lw(35.0n).
-            Rust-based tools and to build fish from source. All paths
+T{
-            are gated on type -q cargo and degrade gracefully.
+Tool
-starship    Cross-shell prompt; loaded via type -q starship guard.
+T}@T{
-            Without it the Catppuccin nim-style fallback prompt activates.
+Description
-uv          Python package and project manager (Astral); used by the
+T}
-            fish-from-source build path in fish-deps. All consumers
+_
-            degrade gracefully without it.
+T{
-direnv      Per-directory environment loading; integration is fully
+\f[V]cargo\f[R]
-            guarded with type -q direnv. Without it the direnv hook
+T}@T{
-            is simply not loaded and auto-venv activates normally.
+Rust toolchain (via rustup); used by \f[V]fish-deps\f[R] to install
-paru        AUR helper (Arch only; preferred); guarded throughout \[em]
+Rust-based tools and to build fish from source.
-            non-Arch systems silently skip AUR-specific paths.
+All paths are gated on \f[V]type -q cargo\f[R] and degrade gracefully.
-yay         AUR helper (Arch only; fallback to paru); same guards apply.
+T}
-eza         Modern ls replacement
+T{
-lsd         ls replacement (fallback to eza)
+\f[V]starship\f[R]
-bat         Syntax-highlighted cat
+T}@T{
-btop        Modern resource monitor
+Cross-shell prompt; loaded via \f[V]type -q starship\f[R] guard.
-dust        Disk usage tree (Rust)
+Without it the Catppuccin nim-style fallback prompt activates.
-duf         Disk usage/free overview
+T}
-prettyping  Colorized ping wrapper
+T{
-ov          Modern pager (replaces less)
+\f[V]uv\f[R]
-ripgrep     Fast line search
+T}@T{
-lazygit     Terminal git UI
+Python package and project manager (Astral); used by the
-lazydocker  Terminal docker UI
+fish-from-source build path in \f[V]fish-deps\f[R].
-trash       Safe delete (trash-cli)
+All consumers degrade gracefully without it.
-kitty       GPU-accelerated terminal (primary)
+T}
-wezterm     GPU-accelerated terminal (alternative)
+T{
-python3     Standalone interpreter \[em] used by the paru/yay log cleaner.
+\f[V]direnv\f[R]
-            Note: uv does not provide python3 on PATH, and Arch\[aq]s base
+T}@T{
-            does not include it, so it is listed separately. All
+Per-directory environment loading; integration is fully guarded with
-            consumers degrade gracefully without it.
+\f[V]type -q direnv\f[R].
-yt-dlp      Video/media downloader; backs the yt-dlp wrapper function.
+Without it the direnv hook is simply not loaded and auto-venv activates
-            Optional \[em] the wrapper falls back to the system yt-dlp and
+normally.
-            the rest of the config works without it.
+T}
-\f[R]
+T{
-.fi
+\f[V]paru\f[R]
+T}@T{
+AUR helper (Arch only; preferred); guarded throughout \[em] non-Arch
+systems silently skip AUR-specific paths.
+T}
+T{
+\f[V]yay\f[R]
+T}@T{
+AUR helper (Arch only; fallback to paru); same guards apply.
+T}
+T{
+\f[V]eza\f[R]
+T}@T{
+Modern \f[V]ls\f[R] replacement
+T}
+T{
+\f[V]lsd\f[R]
+T}@T{
+\f[V]ls\f[R] replacement (fallback to \f[V]eza\f[R])
+T}
+T{
+\f[V]bat\f[R]
+T}@T{
+Syntax-highlighted \f[V]cat\f[R]
+T}
+T{
+\f[V]btop\f[R]
+T}@T{
+Modern resource monitor
+T}
+T{
+\f[V]dust\f[R]
+T}@T{
+Disk usage tree (Rust)
+T}
+T{
+\f[V]duf\f[R]
+T}@T{
+Disk usage/free overview
+T}
+T{
+\f[V]prettyping\f[R]
+T}@T{
+Colorized ping wrapper
+T}
+T{
+\f[V]ov\f[R]
+T}@T{
+Modern pager (replaces \f[V]less\f[R])
+T}
+T{
+\f[V]ripgrep\f[R]
+T}@T{
+Fast line search
+T}
+T{
+\f[V]lazygit\f[R]
+T}@T{
+Terminal git UI
+T}
+T{
+\f[V]lazydocker\f[R]
+T}@T{
+Terminal docker UI
+T}
+T{
+\f[V]trash\f[R]
+T}@T{
+Safe delete (\f[V]trash-cli\f[R])
+T}
+T{
+\f[V]kitty\f[R]
+T}@T{
+GPU-accelerated terminal (primary)
+T}
+T{
+\f[V]wezterm\f[R]
+T}@T{
+GPU-accelerated terminal (alternative)
+T}
+T{
+\f[V]python3\f[R]
+T}@T{
+Standalone interpreter \[em] used by the \f[V]paru\f[R]/\f[V]yay\f[R]
+log cleaner.
+Note: \f[V]uv\f[R] does not provide \f[V]python3\f[R] on PATH, and
+Arch\[cq]s base does not include it, so it is listed separately.
+All consumers degrade gracefully without it.
+T}
+T{
+\f[V]yt-dlp\f[R]
+T}@T{
+Video/media downloader; backs the \f[V]yt-dlp\f[R] wrapper function.
+Optional \[em] the wrapper falls back to the system \f[V]yt-dlp\f[R] and
+the rest of the config works without it.
+T}
+.TE
 .SS Install Methods
 .PP
 The install priority for each tool:
-.IP
+.PP
-.nf
+.TS
-\f[C]
+tab(@);
-cargo     Rust tools (eza, lsd, bat, dust, ov, ripgrep, trashy, zoxide,
+lw(35.0n) lw(35.0n).
-          starship) \[em] always gets the latest crate version
+T{
-system PM paru / apt / brew / dnf / etc. \[em] for tools without a crate
+Method
-git clone fzf \[em] installed from GitHub to \[ti]/.fzf/
+T}@T{
-curl      starship installer, fisher bootstrap, uv installer
+Packages
-\f[R]
+T}
-.fi
+_
+T{
+\f[V]cargo\f[R]
+T}@T{
+Rust tools (\f[V]eza\f[R], \f[V]lsd\f[R], \f[V]bat\f[R], \f[V]dust\f[R],
+\f[V]ov\f[R], \f[V]ripgrep\f[R], \f[V]trashy\f[R], \f[V]zoxide\f[R],
+\f[V]starship\f[R]) \[em] always gets the latest crate version
+T}
+T{
+system PM
+T}@T{
+\f[V]paru\f[R] / \f[V]apt\f[R] / \f[V]brew\f[R] / \f[V]dnf\f[R] / etc.
+\[em] for tools without a crate
+T}
+T{
+\f[V]git clone\f[R]
+T}@T{
+\f[V]fzf\f[R] \[em] installed from GitHub to \f[V]\[ti]/.fzf/\f[R]
+T}
+T{
+\f[V]curl\f[R]
+T}@T{
+\f[V]starship\f[R] installer, \f[V]fisher\f[R] bootstrap, \f[V]uv\f[R]
+installer
+T}
+.TE
 .PP
    *   *   *   *   *
 .SH 7. CUSTOMIZATION
+.PP
+This section explains how to adapt the configuration to your specific
+workflow, including local machine overrides and opinionated component
+toggles.
 .SS Machine-local Configuration
 .PP
 Place machine-specific settings that should not be committed to git in:
@@ -3704,6 +4015,9 @@ local.fish in turn sources secrets.fish when it exists.
 .PP
    *   *   *   *   *
 .SH 11. TROUBLESHOOTING
+.PP
+This section covers common issues, their solutions, and how to safely
+revert changes or uninstall the configuration entirely.
 .SS Uninstalling / Reverting to Backup
 .PP
 The installation step backs up any existing config to