docs: use markdown tables for abbreviations

Generates actual markdown tables instead of indented text blocks to ensure MDX/Starlight correctly renders abbreviations.

conf.d/abbr.fish

@@ -9,81 +9,167 @@
 # It is sourced by Fish on startup.
 
 # Neovim
+# @category Editors
+# @desc nvim
 abbr -a n nvim
+# @category Editors
+# @desc nvim
 abbr -a nv nvim
+# @category Editors
+# @desc nvim
 abbr -a neovim nvim
+# @category Editors
+# @desc cd ~/.config/nvim
 abbr -a cdnv 'cd ~/.config/nvim # Neovim Config'
+# @category Editors
+# @desc cd ~/.config/nvim; nvim
 abbr -a cdnvn 'cd ~/.config/nvim;nvim'
 # VSCode
+# @category AI Assistants
+# @desc antigravity-ide
 abbr -a v antigravity-ide
 # Kate
+# @category Editors
+# @desc kate
 abbr -a k kate
 # WezTerm SSH
 if test "$TERM_PROGRAM" = WezTerm
+    # @category AI Assistants
+    # @desc wezterm ssh (WezTerm only)
     abbr -a s wezterm ssh
 end
 # Neovim in a new tab
 if test "$TERM" = xterm-kitty
+    # @category Terminal Windows, Tabs, and Panes
+    # @desc Open new tab with nvim (terminal-aware)
     abbr -a editt kitty @ launch --type=tab --cwd=current nvim # Kitty
 end
 if test "$TERM_PROGRAM" = WezTerm
+    # @category Terminal Windows, Tabs, and Panes
+    # @desc Open new tab with nvim (terminal-aware)
     abbr -a editt wezterm cli spawn nvim # WezTerm
 end
 # LazyGit
+# @category Git
+# @desc lazygit
 abbr -a lg lazygit
 # Sudo shell
+# @category Miscellaneous
+# @desc sudo -s
 abbr -a sudu sudo -s
 # Kitty
 if test "$TERM" = xterm-kitty
+    # @category Miscellaneous
+    # @desc kitty (Kitty only)
     abbr -a kt kitty
 end
 # cat
+# @category Miscellaneous
+# @desc cat
 abbr -a c cat
 # chezmoi
+# @category Chezmoi
+# @desc chezmoi
 abbr -a cm chezmoi
 # chezmoi cd
+# @category Chezmoi
+# @desc chezmoi cd
 abbr -a cmcd chezmoi cd
+# @category Chezmoi
+# @desc chezmoi cd
 abbr -a czcd chezmoi cd
+# @category Chezmoi
+# @desc chezmoi cd
 abbr -a cdcm chezmoi cd
+# @category Chezmoi
+# @desc chezmoi cd
 abbr -a cdcz chezmoi cd
 # chezmoi edit
+# @category Chezmoi
+# @desc chezmoi edit
 abbr -a cme chezmoi edit
+# @category Chezmoi
+# @desc chezmoi edit
 abbr -a cze chezmoi edit
 # chezmoi add
+# @category Chezmoi
+# @desc chezmoi add
 abbr -a cmad chezmoi add
+# @category Chezmoi
+# @desc chezmoi add
 abbr -a czad chezmoi add
 # chezmoi apply
+# @category Chezmoi
+# @desc chezmoi apply
 abbr -a cmap chezmoi apply
+# @category Chezmoi
+# @desc chezmoi apply
 abbr -a czap chezmoi apply
 # chezmoi rm
+# @category Chezmoi
+# @desc chezmoi forget
 abbr -a cmrm chezmoi forget
+# @category Chezmoi
+# @desc chezmoi forget
 abbr -a cmf chezmoi forget
+# @category Chezmoi
+# @desc chezmoi forget
 abbr -a czrm chezmoi forget
+# @category Chezmoi
+# @desc chezmoi forget
 abbr -a czf chezmoi forget
 # chezmoi init
+# @category Chezmoi
+# @desc chezmoi init
 abbr -a cmi chezmoi init
+# @category Chezmoi
+# @desc chezmoi init
 abbr -a czi chezmoi init
 # Edit
+# @category Editors
+# @desc edit
 abbr -a e edit
 # Sudoedit
+# @category Editors
+# @desc sudoedit
 abbr -a se sudoedit
 # Git
+# @category Git
+# @desc git
 abbr -a g git
+# @category Git
+# @desc generate .gitignore
 abbr -a gitig gi
+# @category Git
+# @desc generate .gitignore
 abbr -a git-ignore gi
 # Antigravity
+# @category AI Assistants
+# @desc agy
 abbr -a ag agy
+# @category AI Assistants
+# @desc agy .
 abbr -a ag. agy .
 # Quit
+# @category Miscellaneous
+# @desc exit
 abbr -a /exit exit
 # Window-management abbreviations are opinionated (C4 integrations)
 if __fish_config_op_enabled __fish_config_op_integrations
     if test "$TERM" = xterm-kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Close current pane/window
         abbr -a :q kitty @ close-window # Kitty (Closes the active split/pane)
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Close current tab
         abbr -a :Q kitty @ close-tab # Kitty (Closes the whole tab)
     end
     if test "$TERM_PROGRAM" = WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Close current pane/window
         abbr -a :q wezterm cli kill-pane # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Close current tab
         abbr -a :Q wezterm cli kill-pane # WezTerm
     end
 end
@@ -91,19 +177,33 @@ end
 ######### Alternates ##########
 ### ls alternates
 # List all files
+# @category Navigation and Listing
+# @desc ls
 abbr -a l ls
 # List all files by size
+# @category Navigation and Listing
+# @desc lss (sort by size)
 abbr -a lS lss
 # List all files by reverse modified time
+# @category Navigation and Listing
+# @desc lsr (sort by time, oldest first)
 abbr -a lsR lsr
 # List by extension
+# @category Navigation and Listing
+# @desc lx (sort by extension)
 abbr -a lX lx
 # Tree listing (depth 2)
+# @category Navigation and Listing
+# @desc lt (tree, depth 2)
 abbr -a lT lt
 # Full tree listing
+# @category Navigation and Listing
+# @desc lstree (full recursive tree)
 abbr -a lsT lstree
 ### speed-test alternates
 # Speedtest using fast.com
+# @category Miscellaneous
+# @desc fast-cli
 abbr -a speedtest-fast fast-cli
 
 # Kitty/WezTerm window-management abbreviations are opinionated (C4
@@ -111,222 +211,484 @@ abbr -a speedtest-fast fast-cli
 if __fish_config_op_enabled __fish_config_op_integrations
     # Window Creation (OS Windows)
     if test "$TERM" = xterm-kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New OS window
         abbr -a :w kitty @ launch --type=os-window # Kitty
     end
     if test "$TERM_PROGRAM" = WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New OS window
         abbr -a :w wezterm cli spawn --new-window # WezTerm
     end
 
     # Window Splits (Panes)
     if test "$TERM" = xterm-kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split pane horizontally (new pane below)
         abbr -a :wv kitty @ launch --location=hsplit # Kitty (Horizontal split)
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split pane vertically (new pane to the right)
         abbr -a :wh kitty @ launch --location=vsplit # Kitty (Vertical split)
     end
     if test "$TERM_PROGRAM" = WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split pane horizontally (new pane below)
         abbr -a :wv wezterm cli split-pane --bottom # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split pane vertically (new pane to the right)
         abbr -a :wh wezterm cli split-pane --right # WezTerm
     end
 
     # Window Detach (Move Pane)
     if test "$TERM" = xterm-kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Detach current window to its own OS window
         abbr -a :wo kitty @ detach-window --target-tab=new # Kitty (Moves pane to new tab)
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Move current pane to a new tab
         abbr -a :wot kitty @ detach-window # Kitty (Same as above, default behavior)
     end
     if test "$TERM_PROGRAM" = WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Detach current window to its own OS window
         abbr -a :wo wezterm cli move-pane-to-new-tab --new-window # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Move current pane to a new tab
         abbr -a :wot wezterm cli move-pane-to-new-tab # WezTerm
     end
 
     # Tab Creation
     if test "$TERM" = xterm-kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New tab
         abbr -a :t kitty @ launch --type=tab # Kitty
     end
     if test "$TERM_PROGRAM" = WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New tab
         abbr -a :t wezterm cli spawn # WezTerm
     end
 
     # Rename Tab
     if test "$TERM" = xterm-kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Set tab title
         abbr -a :tl "kitty @ set-tab-title" # Kitty -> Usage: :tl "New Title"
     end
     if test "$TERM_PROGRAM" = WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Set tab title
         abbr -a :tl wezterm cli set-tab-title # WezTerm
     end
 
     # Rename Window
     if test "$TERM" = xterm-kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Set window title
         abbr -a :tw "kitty @ set-window-title" # Kitty
     end
     if test "$TERM_PROGRAM" = WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Set window title
         abbr -a :tw wezterm cli set-window-title # WezTerm
     end
 
     # Rename Workspace
     if test "$TERM_PROGRAM" = WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Rename workspace (WezTerm only)
         abbr -a :twk wezterm cli rename-workspace # WezTerm
     end
     # Kitty does not have a direct CLI equivalent for renaming a dynamic "workspace" session.
 
     # Tab Navigation
     if test "$TERM" = xterm-kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Focus previous tab
         abbr -a :tp "kitty @ focus-tab --match neighbor:left" # Kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Focus next tab
         abbr -a :tn "kitty @ focus-tab --match neighbor:right" # Kitty
     end
     if test "$TERM_PROGRAM" = WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Focus previous tab
         abbr -a :tp wezterm cli activate-tab --tab-relative -1 # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Focus next tab
         abbr -a :tn wezterm cli activate-tab --tab-relative 1 # WezTerm
     end
 
     # Specialty Tab Shortcuts (New Tab in specific dir)
     if test "$TERM" = xterm-kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New tab at ~/.config/kitty
         abbr -a :tgk kitty @ launch --type=tab --cwd ~/.config/kitty # Kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New tab at ~/.config/nvim
         abbr -a :tgn kitty @ launch --type=tab --cwd ~/.config/nvim # Kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New tab at ~/.config/fish
         abbr -a :tgf kitty @ launch --type=tab --cwd ~/.config/fish # Kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New tab at ~
         abbr -a :tgh kitty @ launch --type=tab --cwd ~
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New tab at ~/.local/share/chezmoi
         abbr -a :tgcz kitty @ launch --type=tab --cwd ~/.local/share/chezmoi # Kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New tab at ~/.config/chezmoi
         abbr -a :tgcm kitty @ launch --type=tab --cwd ~/.config/chezmoi # Kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New tab at ~/projects
         abbr -a :tgp kitty @ launch --type=tab --cwd ~/projects # Kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New tab at / (root)
         abbr -a :tgr kitty @ launch --type=tab -- sudo -i
     end
     if test "$TERM_PROGRAM" = WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New tab at ~/.config/kitty
         abbr -a :tgk wezterm cli spawn --cwd ~/.config/kitty # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New tab at ~/.config/nvim
         abbr -a :tgn wezterm cli spawn --cwd ~/.config/nvim # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New tab at ~/.config/fish
         abbr -a :tgf wezterm cli spawn --cwd ~/.config/fish # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New tab at ~
         abbr -a :tgh wezterm cli spawn --cwd ~ # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New tab at ~/.local/share/chezmoi
         abbr -a :tgcz wezterm cli spawn --cwd ~/.local/share/chezmoi # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New tab at ~/.config/chezmoi
         abbr -a :tgcm wezterm cli spawn --cwd ~/.config/chezmoi # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New tab at ~/projects
         abbr -a :tgp wezterm cli spawn --cwd ~/projects # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New tab at / (root)
         abbr -a :tgr wezterm cli spawn -- sudo -i # WezTerm
     end
 
     # Specialty Window Shortcuts (New OS Window in specific dir)
     if test "$TERM" = xterm-kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New OS window at ~/.config/kitty
         abbr -a :wgk kitty @ launch --type=os-window --cwd ~/.config/kitty # Kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New OS window at ~/.config/nvim
         abbr -a :wgn kitty @ launch --type=os-window --cwd ~/.config/nvim # Kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New OS window at ~/.config/fish
         abbr -a :wgf kitty @ launch --type=os-window --cwd ~/.config/fish # Kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New OS window at ~
         abbr -a :wgh kitty @ launch --type=os-window --cwd ~
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New OS window at ~/.local/share/chezmoi
         abbr -a :wgzd kitty @ launch --type=os-window --cwd ~/.local/share/chezmoi # Kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New OS window at ~/.config/chezmoi
         abbr -a :wgcz kitty @ launch --type=os-window --cwd ~/.config/chezmoi # Kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New OS window at ~/projects
         abbr -a :wgp kitty @ launch --type=os-window --cwd ~/projects # Kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New OS window at / (root)
         abbr -a :wgr kitty @ launch --type=os-window -- sudo -i # Kitty
     end
     if test "$TERM_PROGRAM" = WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New OS window at ~/.config/kitty
         abbr -a :wgk wezterm cli spawn --new-window --cwd ~/.config/kitty # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New OS window at ~/.config/nvim
         abbr -a :wgn wezterm cli spawn --new-window --cwd ~/.config/nvim # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New OS window at ~/.config/fish
         abbr -a :wgf wezterm cli spawn --new-window --cwd ~/.config/fish # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New OS window at ~
         abbr -a :wgh wezterm cli spawn --new-window --cwd ~ # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New OS window at ~/.local/share/chezmoi
         abbr -a :wgzd wezterm cli spawn --new-window --cwd ~/.local/share/chezmoi # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New OS window at ~/.config/chezmoi
         abbr -a :wgcz wezterm cli spawn --new-window --cwd ~/.config/chezmoi # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New OS window at ~/projects
         abbr -a :wgp wezterm cli spawn --new-window --cwd ~/projects # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc New OS window at / (root)
         abbr -a :wgr wezterm cli spawn --new-window -- sudo -i # WezTerm
     end
 
     # Specialty Window Vertical Shortcuts (Split Bottom)
     if test "$TERM" = xterm-kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split bottom at ~/.config/kitty
         abbr -a :wvgk kitty @ launch --location=hsplit --cwd ~/.config/kitty # Kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split bottom at ~/.config/nvim
         abbr -a :wvgn kitty @ launch --location=hsplit --cwd ~/.config/nvim # Kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split bottom at ~/.config/fish
         abbr -a :wvgf kitty @ launch --location=hsplit --cwd ~/.config/fish # Kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split bottom at ~
         abbr -a :wvgh kitty @ launch --location=hsplit --cwd ~ # Kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split bottom at ~/.local/share/chezmoi
         abbr -a :wvgcz kitty @ launch --location=hsplit --cwd ~/.local/share/chezmoi # Kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split bottom at ~/.config/chezmoi
         abbr -a :wvgcm kitty @ launch --location=hsplit --cwd ~/.config/chezmoi # Kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split bottom at ~/projects
         abbr -a :wvgp kitty @ launch --location=hsplit --cwd ~/projects # Kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split bottom at / (root)
         abbr -a :wvgr kitty @ launch --location=hsplit -- sudo -i # Kitty
     end
     if test "$TERM_PROGRAM" = WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split bottom at ~/.config/kitty
         abbr -a :wvgk wezterm cli split-pane --bottom --cwd ~/.config/kitty # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split bottom at ~/.config/nvim
         abbr -a :wvgn wezterm cli split-pane --bottom --cwd ~/.config/nvim # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split bottom at ~/.config/fish
         abbr -a :wvgf wezterm cli split-pane --bottom --cwd ~/.config/fish # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split bottom at ~
         abbr -a :wvgh wezterm cli split-pane --bottom --cwd ~ # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split bottom at ~/.local/share/chezmoi
         abbr -a :wvgcz wezterm cli split-pane --bottom --cwd ~/.local/share/chezmoi # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split bottom at ~/.config/chezmoi
         abbr -a :wvgcm wezterm cli split-pane --bottom --cwd ~/.config/chezmoi # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split bottom at ~/projects
         abbr -a :wvgp wezterm cli split-pane --bottom --cwd ~/projects # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split bottom at / (root)
         abbr -a :wvgr wezterm cli split-pane --bottom -- sudo -i # WezTerm
     end
 
     # Specialty Window Horizontal Shortcuts (Split Right)
     if test "$TERM" = xterm-kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split right at ~/.config/kitty
         abbr -a :whgk kitty @ launch --location=vsplit --cwd ~/.config/kitty # Kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split right at ~/.config/nvim
         abbr -a :whgn kitty @ launch --location=vsplit --cwd ~/.config/nvim # Kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split right at ~/.config/fish
         abbr -a :whgf kitty @ launch --location=vsplit --cwd ~/.config/fish # Kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split right at ~
         abbr -a :whgh kitty @ launch --location=vsplit --cwd ~ # Kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split right at ~/.local/share/chezmoi
         abbr -a :whgcz kitty @ launch --location=vsplit --cwd ~/.local/share/chezmoi # Kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split right at ~/.config/chezmoi
         abbr -a :whgcm kitty @ launch --location=vsplit --cwd ~/.config/chezmoi # Kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split right at ~/projects
         abbr -a :whgp kitty @ launch --location=vsplit --cwd ~/projects # Kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split right at / (root)
         abbr -a :whgr kitty @ launch --location=vsplit --cwd current sudo -i # Kitty -> Specialty cd Shortcuts
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc cd ~/.config/kitty
         abbr -a :cdk 'cd ~/.config/kitty/ # Kitty Config'
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc cd ~/.config/kitty; nvim
         abbr -a :cdkn 'cd ~/.config/kitty;nvim'
     end
     if test "$TERM_PROGRAM" = WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split right at ~/.config/kitty
         abbr -a :whgk wezterm cli split-pane --bottom --cwd ~/.config/kitty # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split right at ~/.config/nvim
         abbr -a :whgn wezterm cli split-pane --bottom --cwd ~/.config/nvim # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split right at ~/.config/fish
         abbr -a :whgf wezterm cli split-pane --bottom --cwd ~/.config/fish # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split right at ~
         abbr -a :whgh wezterm cli split-pane --bottom --cwd ~ # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split right at ~/.local/share/chezmoi
         abbr -a :whgcz wezterm cli split-pane --bottom --cwd ~/.local/share/chezmoi # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split right at ~/.config/chezmoi
         abbr -a :whgcm wezterm cli split-pane --bottom --cwd ~/.config/chezmoi # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split right at ~/projects
         abbr -a :whgp wezterm cli split-pane --bottom --cwd ~/projects # WezTerm
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Split right at / (root)
         abbr -a :whgr wezterm cli split-pane --bottom -- sudo -i # WezTerm
     end
+    # @category Terminal Windows, Tabs, and Panes
+    # @desc cd ~/.config/nvim
     abbr -a :cdn cd '~/.config/nvim/ # Neovim Config'
+    # @category Terminal Windows, Tabs, and Panes
+    # @desc cd ~/.config/nvim; nvim
     abbr -a :cdnn 'cd ~/.config/nvim;nvim'
+    # @category Terminal Windows, Tabs, and Panes
+    # @desc cd ~/.config/fish
     abbr -a :cdf 'cd ~/.config/fish/ # Fish Config'
+    # @category Terminal Windows, Tabs, and Panes
+    # @desc cd ~/.config/fish; nvim
     abbr -a :cdfn 'cd ~/.config/fish;nvim'
+    # @category Terminal Windows, Tabs, and Panes
+    # @desc cd ~
     abbr -a :cdh 'cd ~ # Home Directory'
+    # @category Terminal Windows, Tabs, and Panes
+    # @desc cd ~; nvim
     abbr -a :cdhn 'cd ~;nvim'
+    # @category Terminal Windows, Tabs, and Panes
+    # @desc cd ~/.local/share/chezmoi
     abbr -a :cdcz cd '~/.local/share/chezmoi/ # Chezmoi Source'
+    # @category Terminal Windows, Tabs, and Panes
+    # @desc cd ~/.local/share/chezmoi; nvim
     abbr -a :cdczn 'cd ~/.local/share/chezmoi;nvim'
+    # @category Terminal Windows, Tabs, and Panes
+    # @desc cd ~/.config/chezmoi
     abbr -a :cdcm 'cd ~/.config/chezmoi/ # Chezmoi Config'
+    # @category Terminal Windows, Tabs, and Panes
+    # @desc cd ~/.config/chezmoi; nvim
     abbr -a :cdcmn 'cd ~/.config/chezmoi;nvim'
+    # @category Terminal Windows, Tabs, and Panes
+    # @desc cd ~/projects/...
     abbr -a :cdp --regex ':cdp' --set-cursor 'cd ~/projects/%'
     # abbr -a cdp_slash --position anywhere --regex ':cdp/' --set-cursor 'cd ~/projects/%'
+    # @category Terminal Windows, Tabs, and Panes
+    # @desc cd ~/projects; nvim
     abbr -a :cdpn 'cd ~/projects;nvim'
+    # @category Terminal Windows, Tabs, and Panes
+    # @desc cd ~/.config/wezterm
     abbr -a :cdw 'cd ~/.config/wezterm/ # WezTerm Config'
+    # @category Terminal Windows, Tabs, and Panes
+    # @desc cd ~/.config/wezterm; nvim
     abbr -a :cdwn 'cd ~/.config/wezterm;nvim'
     if test "$TERM" = xterm-kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc Open new tab with nvim (terminal-aware)
         abbr -a editt kitty @ launch --type tab nvim
     end
     # Spawn window
     if test "$TERM" = xterm-kitty
+        # @category Terminal Windows, Tabs, and Panes
+        # @desc spwin (spawn new OS window)
         abbr -a :sw spwin
     end
 end
 
 ### Docker ###
+# @category Docker
+# @desc docker context use default
 abbr -a dcl 'docker context use default # Local Host'
+# @category Docker
+# @desc ld (lazydocker)
 abbr -a lzd ld
+# @category Docker
+# @desc docker context ls
 abbr -a dcls 'docker context ls'
 
 ### Beads ###
+# @category Miscellaneous
+# @desc bd list
 abbr -a bl 'bd list'
+# @category Miscellaneous
+# @desc bd sync
 abbr -a bs 'bd sync'
+# @category Miscellaneous
+# @desc bd create --title
 abbr -a bC 'bd create --title'
+# @category Miscellaneous
+# @desc bd show
 abbr -a bsh 'bd show'
+# @category Miscellaneous
+# @desc lazybeads
 abbr -a lb lazybeads
 
 ### Systemctl ###
+# @category Systemctl
+# @desc systemctl
 abbr -a sc systemctl
+# @category Systemctl
+# @desc sudo systemctl
 abbr -a ssc 'sudo systemctl'
+# @category Systemctl
+# @desc systemctl --user
 abbr -a scu 'systemctl --user'
+# @category Systemctl
+# @desc systemctl status
 abbr -a st 'systemctl status'
+# @category Systemctl
+# @desc systemctl start
 abbr -a scs 'systemctl start'
+# @category Systemctl
+# @desc systemctl restart
 abbr -a scr 'systemctl restart'
+# @category Systemctl
+# @desc sudo systemctl status
 abbr -a ssct 'sudo systemctl status'
+# @category Systemctl
+# @desc sudo systemctl start
 abbr -a sscs 'sudo systemctl start'
+# @category Systemctl
+# @desc sudo systemctl restart
 abbr -a sscr 'sudo systemctl restart'
 
 ### Alternate command names ###
 # Expand to the canonical function name so muscle-memory typos still work,
 # while surfacing the real command instead of silently forwarding to it.
+# @category Miscellaneous
+# @desc repo-open
 abbr -a open-repo repo-open
+# @category Miscellaneous
+# @desc open-url
 abbr -a url-open open-url
 
 ### History Expansions and Substitutions ###
 # Bash-style history expansion is opinionated (C3 overrides), gated atomically
 # with conf.d/tricks.fish, conf.d/puffer.fish, and functions/expand_*.fish.
 if __fish_config_op_enabled __fish_config_op_overrides
+    # @category History Expansion
+    # @name !^
+    # @desc Expand to the first argument of the previous command
     abbr -a !^ --position anywhere --function expand_bang_caret
+    # @category History Expansion
+    # @name !*
+    # @desc Expand to all arguments of the previous command
     abbr -a '!*' --position anywhere --function expand_bang_all
+    # @category History Expansion
+    # @name ^old^new^
+    # @desc Interactive typo substitution (replace 'old' with 'new' in previous command)
     abbr -a typo_sub --position anywhere --regex '\^([^^]+)\^([^^]*)' --function expand_typo_sub
+    # @category History Expansion
+    # @name !string
+    # @desc Expand to the most recent command starting with 'string'
     abbr -a bang_string --position anywhere --regex '![\w.-]+' --function expand_bang_string
+    # @category History Expansion
+    # @name !?string?
+    # @desc Expand to the most recent command containing 'string'
     abbr -a bang_search --position anywhere --regex '!\?[\w.-]+\??' --function expand_bang_search
+    # @category History Expansion
+    # @name !-n
+    # @desc Expand to the nth-previous command
     abbr -a bang_minus_n --position anywhere --regex '!-(\d+)' --function expand_bang_minus_n
 end

conf.d/bash_expands.fish

@@ -0,0 +1,138 @@
+# Copyright (C) 2026 Rootiest
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# Provides bash-style history expansion functions for abbreviations.
+# These functions are gated by the C3 overrides switch.
+
+# Execute expand_bang_all
+function expand_bang_all --description 'Execute expand_bang_all'
+    # Opinionated guard (C3): no expansion when overrides are disabled.
+    __fish_config_op_enabled __fish_config_op_overrides; or return 1
+
+    set -l token $argv[1]
+    if test -z "$token"; set token (commandline -t); end
+    
+    set -l tokens (string split -n " " -- $history[1])
+    if test (count $tokens) -gt 1
+        echo -- (string join " " -- $tokens[2..-1])
+    else
+        echo -- $token
+    end
+end
+
+# Execute expand_bang_caret
+function expand_bang_caret --description 'Execute expand_bang_caret'
+    # Opinionated guard (C3): no expansion when overrides are disabled.
+    __fish_config_op_enabled __fish_config_op_overrides; or return 1
+
+    # Split the last history item into a list
+    set -l tokens (string split -n ' ' -- $history[1])
+    # tokens[1] is the command, tokens[2] is the first argument
+    if set -q tokens[2]
+        echo -- $tokens[2]
+    end
+end
+
+# Execute expand_bang_minus_n
+function expand_bang_minus_n --description 'Execute expand_bang_minus_n'
+    # Opinionated guard (C3): no expansion when overrides are disabled.
+    __fish_config_op_enabled __fish_config_op_overrides; or return 1
+
+    set -l token $argv[1]
+    if test -z "$token"; set token (commandline -t); end
+    
+    # Extract the number from the regex match
+    if string match -qr '!-(\d+)' -- "$token"
+        set -l n (string match -r '!-(\d+)' -- "$token")[2]
+        
+        if test (count $history) -ge $n
+            echo -- $history[$n]
+        else
+            echo -- $token
+        end
+    else
+        echo -- $token
+    end
+end
+
+# Execute expand_bang_search
+function expand_bang_search --description 'Execute expand_bang_search'
+    # Opinionated guard (C3): no expansion when overrides are disabled.
+    __fish_config_op_enabled __fish_config_op_overrides; or return 1
+
+    set -l token $argv[1]
+    if test -z "$token"
+        set token (commandline -t)
+    end
+    
+    # Extract query: looks for text after !? and before an optional ?
+    set -l query (string match -r '!\?([^?]+)' -- $token)[2]
+    
+    if test -n "$query"
+        # Search history for a match anywhere in the command
+        set -l match (builtin history search --contains --max=1 -- $query)
+        
+        if test -n "$match"
+            echo -- $match
+            return
+        end
+    end
+    
+    echo -- $token
+end
+
+# Execute expand_bang_string
+function expand_bang_string --description 'Execute expand_bang_string'
+    # Opinionated guard (C3): no expansion when overrides are disabled.
+    __fish_config_op_enabled __fish_config_op_overrides; or return 1
+
+    # Fish 4.x passes the matched token as argv[1]
+    set -l token $argv[1]
+    if test -z "$token"
+        set token (commandline -t)
+    end
+    
+    # Remove the '!' to get the search query
+    set -l query (string sub -s 2 -- $token)
+    
+    if test -n "$query"
+        # Search history for a prefix match
+        set -l match (builtin history search --prefix --max=1 -- $query)
+        
+        if test -n "$match"
+            echo -- $match
+            return
+        end
+    end
+    
+    # If no match or empty query, return the token so it doesn't vanish
+    echo -- $token
+end
+
+# Execute expand_typo_sub
+function expand_typo_sub --description 'Execute expand_typo_sub'
+    # Opinionated guard (C3): no expansion when overrides are disabled.
+    __fish_config_op_enabled __fish_config_op_overrides; or return 1
+
+    # In newer Fish, the matched token is often passed as $argv[1]
+    # if the abbr is set up correctly. We'll fallback to commandline just in case.
+    set -l last_cmd $history[1]
+    set -l current_token $argv[1]
+    if test -z "$current_token"
+        set current_token (commandline -t)
+    end
+    
+    if string match -qr '\^([^^]+)\^([^^]*)' -- "$current_token"
+        set -l captured (string match -r '\^([^^]+)\^([^^]*)' -- "$current_token")
+        set -l old $captured[2]
+        set -l new $captured[3]
+        
+        if test -n "$old"
+            # Using -- to ensure strings starting with '-' aren't treated as flags
+            echo -- (string replace -a -- "$old" "$new" "$last_cmd")
+        end
+    else
+        # Return the token itself so it doesn't vanish
+        echo -- "$current_token"
+    end
+end

conf.d/puffer.fish

@@ -13,9 +13,21 @@ function _puffer_fish_key_bindings --on-variable fish_key_bindings
         set modes insert default
     end
 
+    # @category History Expansion
+    # @name !.
+    # @desc Expand .. to ../.. and so on
     bind --mode $modes[1] '.' _puffer_fish_expand_dot
+    # @category History Expansion
+    # @name !!
+    # @desc Expand to the previous command
     bind --mode $modes[1] '!' _puffer_fish_expand_bang
+    # @category History Expansion
+    # @name !$
+    # @desc Expand to the last argument of the previous command
     bind --mode $modes[1] '$' _puffer_fish_expand_buck
+    # @category History Expansion
+    # @name !*
+    # @desc Expand to all arguments of the previous command
     bind --mode $modes[1] '*' _puffer_fish_expand_star
     bind --mode $modes[2] --erase '.' '!' '$' '*'
 end

conf.d/tricks.fish

@@ -60,10 +60,22 @@ if __fish_config_op_enabled __fish_config_op_overrides
 
     # Apply bang-bang key bindings based on current key binding mode
     if [ "$fish_key_bindings" = fish_vi_key_bindings ]
+        # @category History Expansion
+        # @name !!
+        # @desc Expand to the previous command
         bind -Minsert ! __history_previous_command
+        # @category History Expansion
+        # @name !$
+        # @desc Expand to the last argument of the previous command
         bind -Minsert '$' __history_previous_command_arguments
     else
+        # @category History Expansion
+        # @name !!
+        # @desc Expand to the previous command
         bind ! __history_previous_command
+        # @category History Expansion
+        # @name !$
+        # @desc Expand to the last argument of the previous command
         bind '$' __history_previous_command_arguments
     end
 end
@@ -94,23 +106,47 @@ end
 ## Useful aliases
 
 # Navigation short-cuts
+# @category Shell Aliases
+# @desc cd ..
 alias ..='cd ..'
+# @category Shell Aliases
+# @desc cd ../..
 alias ...='cd ../..'
+# @category Shell Aliases
+# @desc cd ../../..
 alias ....='cd ../../..'
+# @category Shell Aliases
+# @desc cd ../../../..
 alias .....='cd ../../../..'
+# @category Shell Aliases
+# @desc cd ../../../../..
 alias ......='cd ../../../../..'
 
 # Silent flag injection into POSIX tools is opinionated (C1 aliasing)
 if __fish_config_op_enabled __fish_config_op_aliases
     # Tools & Core command color overrides
+    # @category Shell Aliases
+    # @desc dir --color=auto
     alias dir='dir --color=auto'
+    # @category Shell Aliases
+    # @desc vdir --color=auto
     alias vdir='vdir --color=auto'
+    # @category Shell Aliases
+    # @desc grep --color=auto
     alias grep='grep --color=auto'
+    # @category Shell Aliases
+    # @desc fgrep --color=auto
     alias fgrep='fgrep --color=auto'
+    # @category Shell Aliases
+    # @desc egrep --color=auto
     alias egrep='egrep --color=auto'
 
     # Safety aliases (Confirmation before overwriting/deleting)
+    # @category Shell Aliases
+    # @desc cp -i
     alias cp="cp -i"
+    # @category Shell Aliases
+    # @desc mv -i
     alias mv="mv -i"
 
     # Force wget to resume partial downloads
@@ -118,9 +154,17 @@ if __fish_config_op_enabled __fish_config_op_aliases
 end
 
 # Archives and networking short-hands
+# @category Shell Aliases
+# @desc tar -acf
 alias tarnow='tar -acf '
+# @category Shell Aliases
+# @desc tar -zxvf
 alias untar='tar -zxvf '
+# @category Shell Aliases
+# @desc nc termbin.com 9999
 alias tb='nc termbin.com 9999'
 
 # System Logs
+# @category Shell Aliases
+# @desc journalctl -p 3 -xb
 alias jctl="journalctl -p 3 -xb"

docs/build-manual.py

@@ -51,6 +51,27 @@ def _with_entries(body: str, path: Path, entries: dict) -> str:
     return "\n\n".join(([body] if body.strip() else []) + blocks)
 
 
+def _with_abbreviations(body: str, abbrs: dict[str, list[dict]]) -> str:
+    """Inject generated abbreviation tables into the document placeholders."""
+    rendered_abbrs = {}
+    for cat, items in abbrs.items():
+        lines_cat = ["| Abbreviation | Description |", "|---|---|"]
+        for abbr in items:
+            name = abbr["name"]
+            desc = abbr["desc"]
+            # Escape pipes if any exist in name or desc
+            name = name.replace("|", "\\|")
+            desc = desc.replace("|", "\\|")
+            lines_cat.append(f"| `{name}` | {desc} |")
+        rendered_abbrs[cat] = "\n".join(lines_cat)
+
+    for cat, table in rendered_abbrs.items():
+        placeholder = f"<!-- GENERATED: {cat} -->"
+        body = body.replace(placeholder, table)
+        
+    return body
+
+
 def build_concat(root: Path) -> str:
     """Concatenate the manual into one ordered markdown document.
 
@@ -77,6 +98,9 @@ def build_concat(root: Path) -> str:
         chunks.append("#" * (depth + 1) + " " + heading)
         if _is_function_page(path, root):
             body = _with_entries(body, path, entries)
+        elif path.stem == "04-abbreviations":
+            abbrs = mt.parse_abbreviations(DOCS.parent / "conf.d")
+            body = _with_abbreviations(body, abbrs)
         if body:
             body = re.sub(r"<LinkButton.*?</LinkButton>\n*", "", body, flags=re.DOTALL)
             body = re.sub(r"\[([^\]]+)\]\(/[^)]+\)", r"\1", body)
@@ -675,6 +699,9 @@ def build_site(root: Path, out: Path) -> list[dict]:
 
         if not is_function_dir:
             target = out / rel
+            if path.stem == "04-abbreviations":
+                abbrs = mt.parse_abbreviations(DOCS.parent / "conf.d")
+                body = _with_abbreviations(body, abbrs)
             target.parent.mkdir(parents=True, exist_ok=True)
             body = _inject_subheading_cards(body)
             _write_prettified(target, _page_fm(fm), prettify(body))

docs/fish-config.md

@@ -364,30 +364,36 @@ some expand differently in Kitty vs WezTerm vs other terminals.
 
 ## 4.1 Editors
 
-    n / nv / neovim    nvim
+| Abbreviation | Description |
-    e                  edit
+|---|---|
-    se                 sudoedit
+| `n` | nvim |
-    k                  kate
+| `nv` | nvim |
-    editt              Open new tab with nvim (terminal-aware)
+| `neovim` | nvim |
-    cdnv               cd ~/.config/nvim
+| `cdnv` | cd ~/.config/nvim |
-    cdnvn              cd ~/.config/nvim; nvim
+| `cdnvn` | cd ~/.config/nvim; nvim |
+| `k` | kate |
+| `e` | edit |
+| `se` | sudoedit |
 
 ## 4.2 Navigation and Listing
 
-    l                  ls
+| Abbreviation | Description |
-    lS                 lss       (sort by size)
+|---|---|
-    lsR                lsr       (sort by time, oldest first)
+| `l` | ls |
-    lX                 lx        (sort by extension)
+| `lS` | lss (sort by size) |
-    lT                 lt        (tree, depth 2)
+| `lsR` | lsr (sort by time, oldest first) |
-    lsT                lstree    (full recursive tree)
+| `lX` | lx (sort by extension) |
-    lzd                ld        (lazydocker)
+| `lT` | lt (tree, depth 2) |
-    cdi                zi        (interactive zoxide picker)
+| `lsT` | lstree (full recursive tree) |
 
 ## 4.3 Git
 
-    g                  git
+| Abbreviation | Description |
-    lg                 lazygit
+|---|---|
-    gitig / git-ignore gi        (generate .gitignore)
+| `lg` | lazygit |
+| `g` | git |
+| `gitig` | generate .gitignore |
+| `git-ignore` | generate .gitignore |
 
 ## 4.4 Terminal Windows, Tabs, and Panes
 
@@ -395,152 +401,183 @@ These abbreviations control the terminal emulator. Each has a Kitty
 variant and a WezTerm variant; the correct one is inserted based on
 `$TERM` or `$TERM_PROGRAM`.
 
-    :w          New OS window
+| Abbreviation | Description |
-    :wv         Split pane horizontally (new pane below)
+|---|---|
-    :wh         Split pane vertically (new pane to the right)
+| `editt` | Open new tab with nvim (terminal-aware) |
-    :wo         Detach current window to its own OS window
+| `:q` | Close current pane/window |
-    :wot        Move current pane to a new tab
+| `:Q` | Close current tab |
-    :t          New tab
+| `:w` | New OS window |
-    :tl         Set tab title
+| `:wv` | Split pane horizontally (new pane below) |
-    :tw         Set window title
+| `:wh` | Split pane vertically (new pane to the right) |
-    :twk        Rename workspace (WezTerm only)
+| `:wo` | Detach current window to its own OS window |
-    :tp         Focus previous tab
+| `:wot` | Move current pane to a new tab |
-    :tn         Focus next tab
+| `:t` | New tab |
-    :q          Close current pane/window
+| `:tl` | Set tab title |
-    :Q          Close current tab
+| `:tw` | Set window title |
-    :sw         spwin (spawn new OS window)
+| `:twk` | Rename workspace (WezTerm only) |
-
+| `:tp` | Focus previous tab |
-Quick-navigate shortcuts open windows/tabs/panes with preset working dirs:
+| `:tn` | Focus next tab |
-
+| `:tgk` | New tab at ~/.config/kitty |
-    :tgk    New tab at ~/.config/kitty
+| `:tgn` | New tab at ~/.config/nvim |
-    :tgn    New tab at ~/.config/nvim
+| `:tgf` | New tab at ~/.config/fish |
-    :tgf    New tab at ~/.config/fish
+| `:tgh` | New tab at ~ |
-    :tgh    New tab at ~
+| `:tgcz` | New tab at ~/.local/share/chezmoi |
-    :tgcz   New tab at chezmoi source dir
+| `:tgcm` | New tab at ~/.config/chezmoi |
-    :tgcm   New tab at chezmoi source dir
+| `:tgp` | New tab at ~/projects |
-    :tgp    New tab at ~/projects
+| `:tgr` | New tab at / (root) |
-    :tgr    New tab at / (root)
+| `:wgk` | New OS window at ~/.config/kitty |
-
+| `:wgn` | New OS window at ~/.config/nvim |
-Prefixes :wg* and :wvg* / :whg* open OS windows or splits to the same
+| `:wgf` | New OS window at ~/.config/fish |
-set of dirs, respectively.
+| `:wgh` | New OS window at ~ |
-
+| `:wgzd` | New OS window at ~/.local/share/chezmoi |
-Prefixes :cd* open tabs with a quick cd shortcut:
+| `:wgcz` | New OS window at ~/.config/chezmoi |
-
+| `:wgp` | New OS window at ~/projects |
-    :cdn    cd ~/.config/nvim
+| `:wgr` | New OS window at / (root) |
-    :cdf    cd ~/.config/fish
+| `:wvgk` | Split bottom at ~/.config/kitty |
-    :cdh    cd ~
+| `:wvgn` | Split bottom at ~/.config/nvim |
-    :cdcz   cd to chezmoi source
+| `:wvgf` | Split bottom at ~/.config/fish |
-    :cdp    cd ~/projects
+| `:wvgh` | Split bottom at ~ |
-
+| `:wvgcz` | Split bottom at ~/.local/share/chezmoi |
-Appending n to any :cd* abbreviation also runs nvim after changing dir.
+| `:wvgcm` | Split bottom at ~/.config/chezmoi |
+| `:wvgp` | Split bottom at ~/projects |
+| `:wvgr` | Split bottom at / (root) |
+| `:whgk` | Split right at ~/.config/kitty |
+| `:whgn` | Split right at ~/.config/nvim |
+| `:whgf` | Split right at ~/.config/fish |
+| `:whgh` | Split right at ~ |
+| `:whgcz` | Split right at ~/.local/share/chezmoi |
+| `:whgcm` | Split right at ~/.config/chezmoi |
+| `:whgp` | Split right at ~/projects |
+| `:whgr` | Split right at / (root) |
+| `:cdk` | cd ~/.config/kitty |
+| `:cdkn` | cd ~/.config/kitty; nvim |
+| `:cdn` | cd ~/.config/nvim |
+| `:cdnn` | cd ~/.config/nvim; nvim |
+| `:cdf` | cd ~/.config/fish |
+| `:cdfn` | cd ~/.config/fish; nvim |
+| `:cdh` | cd ~ |
+| `:cdhn` | cd ~; nvim |
+| `:cdcz` | cd ~/.local/share/chezmoi |
+| `:cdczn` | cd ~/.local/share/chezmoi; nvim |
+| `:cdcm` | cd ~/.config/chezmoi |
+| `:cdcmn` | cd ~/.config/chezmoi; nvim |
+| `:cdp` | cd ~/projects/... |
+| `:cdpn` | cd ~/projects; nvim |
+| `:cdw` | cd ~/.config/wezterm |
+| `:cdwn` | cd ~/.config/wezterm; nvim |
+| `:sw` | spwin (spawn new OS window) |
 
 ## 4.5 Chezmoi
 
-    cm / cme / cmi / cmap / cmad / cmrm / cmcd /
+| Abbreviation | Description |
-    cz / cze / czi / czap / czad / czrm / czcd
+|---|---|
-
+| `cm` | chezmoi |
-    cm / cz          chezmoi
+| `cmcd` | chezmoi cd |
-    cmcd / czcd      chezmoi cd
+| `czcd` | chezmoi cd |
-    cme / cze        chezmoi edit
+| `cdcm` | chezmoi cd |
-    cmad / czad      chezmoi add
+| `cdcz` | chezmoi cd |
-    cmap / czap      chezmoi apply
+| `cme` | chezmoi edit |
-    cmrm / cmf / czrm / czf    chezmoi forget
+| `cze` | chezmoi edit |
-    cmi / czi        chezmoi init
+| `cmad` | chezmoi add |
+| `czad` | chezmoi add |
+| `cmap` | chezmoi apply |
+| `czap` | chezmoi apply |
+| `cmrm` | chezmoi forget |
+| `cmf` | chezmoi forget |
+| `czrm` | chezmoi forget |
+| `czf` | chezmoi forget |
+| `cmi` | chezmoi init |
+| `czi` | chezmoi init |
 
 ## 4.6 Docker
 
-    dcl         docker context use default
+| Abbreviation | Description |
-    dcls        docker context ls
+|---|---|
-    lzd         ld (lazydocker)
+| `dcl` | docker context use default |
+| `lzd` | ld (lazydocker) |
+| `dcls` | docker context ls |
 
 ## 4.7 Systemctl
 
-    sc          systemctl
+| Abbreviation | Description |
-    ssc         sudo systemctl
+|---|---|
-    scu         systemctl --user
+| `sc` | systemctl |
-    st          systemctl status
+| `ssc` | sudo systemctl |
-    scs         sudo systemctl start
+| `scu` | systemctl --user |
-    scr         sudo systemctl restart
+| `st` | systemctl status |
-    ssct        sudo systemctl start
+| `scs` | systemctl start |
-    sscs        sudo systemctl stop
+| `scr` | systemctl restart |
-    sscr        sudo systemctl restart
+| `ssct` | sudo systemctl status |
+| `sscs` | sudo systemctl start |
+| `sscr` | sudo systemctl restart |
 
 ## 4.8 AI Assistants
 
-    ag          agy
+| Abbreviation | Description |
-    ag.         agy .
+|---|---|
-    v           antigravity-ide
+| `v` | antigravity-ide |
-    s           wezterm ssh (WezTerm only)
+| `s` | wezterm ssh (WezTerm only) |
+| `ag` | agy |
+| `ag.` | agy . |
 
-## 4.9 History Expansion
+## 4.9 Miscellaneous
 
-These are implemented as keybinding helpers, but can also be typed:
+| Abbreviation | Description |
+|---|---|
+| `sudu` | sudo -s |
+| `kt` | kitty (Kitty only) |
+| `c` | cat |
+| `/exit` | exit |
+| `speedtest-fast` | fast-cli |
+| `bl` | bd list |
+| `bs` | bd sync |
+| `bC` | bd create --title |
+| `bsh` | bd show |
+| `lb` | lazybeads |
+| `open-repo` | repo-open |
+| `url-open` | open-url |
 
-    !^          Expand to first argument of previous command
+## 4.10 Shell Aliases
-    !*          Expand to all arguments of previous command
-    typo_sub    Interactive typo substitution (Ctrl+F)
-    bang_string !string expansion
-    bang_search !?string search
-    bang_minus_n  !-n  (nth-previous command)
-
-## 4.10 Miscellaneous
-
-    /exit       exit
-    :q          Close pane (alias for terminal close)
-    :Q          Close tab
-    sudu        sudo -s
-    kt          kitty (Kitty only)
-    c           cat
-    speedtest-fast  fast-cli
-    bl          bd list
-    bs          bd sync
-    bC          bd create --title
-    bsh         bd show
-    lb          lazybeads
-
-## 4.11 Shell Aliases
 
 These aliases are defined in conf.d/tricks.fish via alias (which creates Fish
 functions). They are active in all interactive sessions.
 
-### Navigation
+| Abbreviation | Description |
+|---|---|
+| `..` | cd .. |
+| `...` | cd ../.. |
+| `....` | cd ../../.. |
+| `.....` | cd ../../../.. |
+| `......` | cd ../../../../.. |
+| `dir` | dir --color=auto |
+| `vdir` | vdir --color=auto |
+| `grep` | grep --color=auto |
+| `fgrep` | fgrep --color=auto |
+| `egrep` | egrep --color=auto |
+| `cp` | cp -i |
+| `mv` | mv -i |
+| `tarnow` | tar -acf |
+| `untar` | tar -zxvf |
+| `tb` | nc termbin.com 9999 |
+| `jctl` | journalctl -p 3 -xb |
 
-    ..      cd ..
+## 4.11 History Expansion
-    ...     cd ../..
-    ....    cd ../../..
-    .....   cd ../../../..
-    ......  cd ../../../../..
 
-### Color Overrides
+Bash-style history expansions trigger on Space or Enter. Some are implemented
+as abbreviations (e.g. `!*`), while others (`!!`, `!$`, `!.`) are implemented
+as keybindings, but they all serve the same purpose.
 
-Force color output for common tools:
+| Abbreviation | Description |
-
+|---|---|
-    grep    grep --color=auto
+| `!^` | Expand to the first argument of the previous command |
-    fgrep   fgrep --color=auto
+| `!*` | Expand to all arguments of the previous command |
-    egrep   egrep --color=auto
+| `^old^new^` | Interactive typo substitution (replace 'old' with 'new' in previous command) |
-    dir     dir --color=auto
+| `!string` | Expand to the most recent command starting with 'string' |
-    vdir    vdir --color=auto
+| `!?string?` | Expand to the most recent command containing 'string' |
-
+| `!-n` | Expand to the nth-previous command |
-### Safety Wrappers
+| `!!` | Expand to the previous command |
-
+| `!$` | Expand to the last argument of the previous command |
-Add -i (interactive confirmation) to destructive commands:
+| `!.` | Expand .. to ../.. and so on |
-
-    cp      cp -i
-    mv      mv -i
-
-### Archives and Networking
-
-    tarnow  tar -acf              Create compressed archive (auto-detects format)
-    untar   tar -zxvf             Extract a gzip-compressed archive
-    wget    wget -c               Resume interrupted downloads by default
-    tb      nc termbin.com 9999   Pipe content to termbin.com for quick sharing
-
-### System Logs
-
-    jctl    journalctl -p 3 -xb   Show priority-3 (error) journal entries
-                                    from the current boot
-
----
 
 # 5. FUNCTIONS REFERENCE
 
@@ -1484,31 +1521,24 @@ Add -i (interactive confirmation) to destructive commands:
 
 ### jobrunner
 
-    Synopsis:  jobrunner [<subcommand>] [<name>] [<command>...]
+    Synopsis:  jobrunner [-t <tool>] [<subcommand>] [<name>] [<command>...]
-               jr [<subcommand>] [<name>] [<command>...]
+               jr [-t <tool>] [<subcommand>] [<name>] [<command>...]
 
     Runs, lists, inspects, re-attaches to, and terminates named background
-    jobs using GNU screen as the process engine. Unlike bkg and detach,
+    jobs using tmux or GNU screen as the process engine. Unlike bkg and
-    which discard output, a jobrunner job keeps a live terminal you can
+    detach, which discard output, a jobrunner job keeps a live terminal you
-    return to later — it survives closing the shell, and `attach` restores
+    can return to later — it survives closing the shell, and `attach`
-    it in any subsequent session.
+    restores it in any subsequent session.
+    Run and manage named background jobs. Jobs are detached from the shell
+    and backed by tmux (preferred) or GNU screen.
 
-    Every subcommand has a matching flag form, and the common cases are
+    If the job name is omitted when starting a new job (e.g. `jobrunner sleep 1`),
-    inferred: no arguments lists jobs, a lone name attaches to it, and a
+    a memorable, random name (like `sleepy-badger`) will be generated.
-    name followed by a command runs it.
-
-    Arguments:
-      run, -r, --run <name> <cmd>...   Start a named job in the background
-      list, -l, --list                 List all managed background jobs
-      attach, -a, --attach <name>      Re-attach interactively to a job
-      kill, -k, --kill <name>          Terminate a running background job
-      logs, -o, --output <name>        Print a job's current output, no attach
-      help, -h, --help                 Show usage help
 
     Exit Status:
       0    Command succeeded, or no jobs are running
       1    Invalid arguments, or the named job does not exist
-      127  screen is not installed
+      127  neither tmux nor screen is installed
 
     Notes:
       Detach from an attached job with Ctrl-A then D; the job keeps running.
@@ -1517,14 +1547,15 @@ Add -i (interactive confirmation) to destructive commands:
       `jobrunner run sync fish -c 'a | b'`.
 
     Example:
-    jobrunner run build make -j8
+    jobrunner run -n build make -j8
-    jobrunner backup rsync -a ./data remote:/backup/
+    jobrunner sleep 1000
+    jobrunner -t screen run -n backup rsync -a ./data remote:/backup/
     jobrunner list
     jobrunner logs build
     jobrunner build
     jobrunner kill build
 
-**Dependencies:** `screen`, `__jobrunner_sessions`
+**Dependencies:** `tmux`, `screen`, `__jobrunner_sessions`
 
 **Used by:** `jr`
 
@@ -2538,6 +2569,40 @@ Add -i (interactive confirmation) to destructive commands:
 
 **Used by:** `repo-open`
 
+### rand_string
+
+    Synopsis:  rand_string [COMPONENTS/MODIFIERS]...
+
+    Generates a random, memorable string using a sequence of specified word
+    categories and formatting modifiers. Words are pulled from curated
+    plain-text databases bundled in `data/words/`.
+
+    Modifiers like `--separator` and `--case` are evaluated sequentially and
+    apply only to the components that follow them.
+
+    Supported Components:
+    <category>      A bundled word list (e.g. adjective, animal, color, name, noun, verb)
+    digits=<N>      N random digits (e.g. digits=3 -> 842)
+    literal=<text>  A static string component (e.g. literal=TEST)
+
+    Arguments:
+      -s, --separator=<sep>   Delimiter for subsequent words (dash, underscore, dot, none, or literal chars)
+      -c, --case=<casing>     Casing for subsequent words (lower, upper, title)
+      -h, --help              Show usage help
+
+    Exit Status:
+      0  String generated successfully
+      1  Unknown category or missing word list file
+
+    Notes:
+      Falls back to `random choice` if GNU `shuf` is missing, but `shuf` is
+      much faster for files with >1000 lines.
+
+    Example:
+    rand_string adjective animal
+    rand_string --case=title color animal --separator=dot digits=4
+    rand_string literal=TEST --separator=underscore verb noun
+
 ### replay
 
     Synopsis:  replay <commands>

docs/manual/04-abbreviations.md

@@ -14,30 +14,15 @@ some expand differently in Kitty vs WezTerm vs other terminals.
 
 ## 4.1 Editors
 
-    n / nv / neovim    nvim
+<!-- GENERATED: Editors -->
-    e                  edit
-    se                 sudoedit
-    k                  kate
-    editt              Open new tab with nvim (terminal-aware)
-    cdnv               cd ~/.config/nvim
-    cdnvn              cd ~/.config/nvim; nvim
 
 ## 4.2 Navigation and Listing
 
-    l                  ls
+<!-- GENERATED: Navigation and Listing -->
-    lS                 lss       (sort by size)
-    lsR                lsr       (sort by time, oldest first)
-    lX                 lx        (sort by extension)
-    lT                 lt        (tree, depth 2)
-    lsT                lstree    (full recursive tree)
-    lzd                ld        (lazydocker)
-    cdi                zi        (interactive zoxide picker)
 
 ## 4.3 Git
 
-    g                  git
+<!-- GENERATED: Git -->
-    lg                 lazygit
-    gitig / git-ignore gi        (generate .gitignore)
 
 ## 4.4 Terminal Windows, Tabs, and Panes
 
@@ -45,149 +30,39 @@ These abbreviations control the terminal emulator. Each has a Kitty
 variant and a WezTerm variant; the correct one is inserted based on
 `$TERM` or `$TERM_PROGRAM`.
 
-    :w          New OS window
+<!-- GENERATED: Terminal Windows, Tabs, and Panes -->
-    :wv         Split pane horizontally (new pane below)
-    :wh         Split pane vertically (new pane to the right)
-    :wo         Detach current window to its own OS window
-    :wot        Move current pane to a new tab
-    :t          New tab
-    :tl         Set tab title
-    :tw         Set window title
-    :twk        Rename workspace (WezTerm only)
-    :tp         Focus previous tab
-    :tn         Focus next tab
-    :q          Close current pane/window
-    :Q          Close current tab
-    :sw         spwin (spawn new OS window)
-
-Quick-navigate shortcuts open windows/tabs/panes with preset working dirs:
-
-    :tgk    New tab at ~/.config/kitty
-    :tgn    New tab at ~/.config/nvim
-    :tgf    New tab at ~/.config/fish
-    :tgh    New tab at ~
-    :tgcz   New tab at chezmoi source dir
-    :tgcm   New tab at chezmoi source dir
-    :tgp    New tab at ~/projects
-    :tgr    New tab at / (root)
-
-Prefixes :wg* and :wvg* / :whg* open OS windows or splits to the same
-set of dirs, respectively.
-
-Prefixes :cd* open tabs with a quick cd shortcut:
-
-    :cdn    cd ~/.config/nvim
-    :cdf    cd ~/.config/fish
-    :cdh    cd ~
-    :cdcz   cd to chezmoi source
-    :cdp    cd ~/projects
-
-Appending n to any :cd* abbreviation also runs nvim after changing dir.
 
 ## 4.5 Chezmoi
 
-    cm / cme / cmi / cmap / cmad / cmrm / cmcd /
+<!-- GENERATED: Chezmoi -->
-    cz / cze / czi / czap / czad / czrm / czcd
-
-    cm / cz          chezmoi
-    cmcd / czcd      chezmoi cd
-    cme / cze        chezmoi edit
-    cmad / czad      chezmoi add
-    cmap / czap      chezmoi apply
-    cmrm / cmf / czrm / czf    chezmoi forget
-    cmi / czi        chezmoi init
 
 ## 4.6 Docker
 
-    dcl         docker context use default
+<!-- GENERATED: Docker -->
-    dcls        docker context ls
-    lzd         ld (lazydocker)
 
 ## 4.7 Systemctl
 
-    sc          systemctl
+<!-- GENERATED: Systemctl -->
-    ssc         sudo systemctl
-    scu         systemctl --user
-    st          systemctl status
-    scs         sudo systemctl start
-    scr         sudo systemctl restart
-    ssct        sudo systemctl start
-    sscs        sudo systemctl stop
-    sscr        sudo systemctl restart
 
 ## 4.8 AI Assistants
 
-    ag          agy
+<!-- GENERATED: AI Assistants -->
-    ag.         agy .
-    v           antigravity-ide
-    s           wezterm ssh (WezTerm only)
 
-## 4.9 History Expansion
+## 4.9 Miscellaneous
 
-These are implemented as keybinding helpers, but can also be typed:
+<!-- GENERATED: Miscellaneous -->
 
-    !^          Expand to first argument of previous command
+## 4.10 Shell Aliases
-    !*          Expand to all arguments of previous command
-    typo_sub    Interactive typo substitution (Ctrl+F)
-    bang_string !string expansion
-    bang_search !?string search
-    bang_minus_n  !-n  (nth-previous command)
-
-## 4.10 Miscellaneous
-
-    /exit       exit
-    :q          Close pane (alias for terminal close)
-    :Q          Close tab
-    sudu        sudo -s
-    kt          kitty (Kitty only)
-    c           cat
-    speedtest-fast  fast-cli
-    bl          bd list
-    bs          bd sync
-    bC          bd create --title
-    bsh         bd show
-    lb          lazybeads
-
-## 4.11 Shell Aliases
 
 These aliases are defined in conf.d/tricks.fish via alias (which creates Fish
 functions). They are active in all interactive sessions.
 
-### Navigation
+<!-- GENERATED: Shell Aliases -->
 
-    ..      cd ..
+## 4.11 History Expansion
-    ...     cd ../..
-    ....    cd ../../..
-    .....   cd ../../../..
-    ......  cd ../../../../..
 
-### Color Overrides
+Bash-style history expansions trigger on Space or Enter. Some are implemented
+as abbreviations (e.g. `!*`), while others (`!!`, `!$`, `!.`) are implemented
+as keybindings, but they all serve the same purpose.
 
-Force color output for common tools:
+<!-- GENERATED: History Expansion -->
-
-    grep    grep --color=auto
-    fgrep   fgrep --color=auto
-    egrep   egrep --color=auto
-    dir     dir --color=auto
-    vdir    vdir --color=auto
-
-### Safety Wrappers
-
-Add -i (interactive confirmation) to destructive commands:
-
-    cp      cp -i
-    mv      mv -i
-
-### Archives and Networking
-
-    tarnow  tar -acf              Create compressed archive (auto-detects format)
-    untar   tar -zxvf             Extract a gzip-compressed archive
-    wget    wget -c               Resume interrupted downloads by default
-    tb      nc termbin.com 9999   Pipe content to termbin.com for quick sharing
-
-### System Logs
-
-    jctl    journalctl -p 3 -xb   Show priority-3 (error) journal entries
-                                    from the current boot
-
----

docs/manualtools.py

@@ -141,6 +141,50 @@ def parse_functions(root: Path) -> dict[str, dict[str, list[str]]]:
     return out
 
 
+def parse_abbreviations(root: Path) -> dict[str, list[dict]]:
+    """Parse annotated abbreviations from conf.d/.
+
+    Returns {category: [{"name": name, "desc": desc}, ...]}
+    """
+    out: dict[str, list[dict]] = {}
+    for filename in ("abbr.fish", "tricks.fish", "puffer.fish"):
+        path = root / filename
+        if not path.exists():
+            continue
+        lines = path.read_text(encoding="utf-8").split("\n")
+        category = None
+        desc = None
+        name_override = None
+        for line in lines:
+            line = line.strip()
+            if line.startswith("# @category "):
+                category = line[12:].strip()
+            elif line.startswith("# @desc "):
+                desc = line[8:].strip()
+            elif line.startswith("# @name "):
+                name_override = line[8:].strip()
+            elif line.startswith("abbr -a ") or line.startswith("bind ") or line.startswith("alias "):
+                if category and desc:
+                    if name_override:
+                        name = name_override
+                    elif line.startswith("abbr -a "):
+                        name = line[8:].strip().split()[0].strip("'\"")
+                    elif line.startswith("alias "):
+                        name = line[6:].strip().split('=')[0]
+                    else:
+                        name = "unknown"
+                    # Only add if we haven't added this name to this category yet
+                    if not any(a["name"] == name for a in out.setdefault(category, [])):
+                        out[category].append({
+                            "name": name,
+                            "desc": desc
+                        })
+                category = None
+                desc = None
+                name_override = None
+    return out
+
+
 def _sort_key(entry: Path) -> tuple:
     """Order by sidebar.order when present, else by filename. Stable."""
     target = entry / "index.md" if entry.is_dir() else entry

functions/expand_bang_all.fish

@@ -1,15 +0,0 @@
-# Execute expand_bang_all
-function expand_bang_all --description 'Execute expand_bang_all'
-    # Opinionated guard (C3): no expansion when overrides are disabled.
-    __fish_config_op_enabled __fish_config_op_overrides; or return 1
-
-    set -l token $argv[1]
-    if test -z "$token"; set token (commandline -t); end
-    
-    set -l tokens (string split -n " " -- $history[1])
-    if test (count $tokens) -gt 1
-        echo -- (string join " " -- $tokens[2..-1])
-    else
-        echo -- $token
-    end
-end

functions/expand_bang_caret.fish

@@ -1,12 +0,0 @@
-# Execute expand_bang_caret
-function expand_bang_caret --description 'Execute expand_bang_caret'
-    # Opinionated guard (C3): no expansion when overrides are disabled.
-    __fish_config_op_enabled __fish_config_op_overrides; or return 1
-
-    # Split the last history item into a list
-    set -l tokens (string split -n ' ' -- $history[1])
-    # tokens[1] is the command, tokens[2] is the first argument
-    if set -q tokens[2]
-        echo -- $tokens[2]
-    end
-end

functions/expand_bang_minus_n.fish

@@ -1,21 +0,0 @@
-# Execute expand_bang_minus_n
-function expand_bang_minus_n --description 'Execute expand_bang_minus_n'
-    # Opinionated guard (C3): no expansion when overrides are disabled.
-    __fish_config_op_enabled __fish_config_op_overrides; or return 1
-
-    set -l token $argv[1]
-    if test -z "$token"; set token (commandline -t); end
-    
-    # Extract the number from the regex match
-    if string match -qr '!-(\d+)' -- "$token"
-        set -l n (string match -r '!-(\d+)' -- "$token")[2]
-        
-        if test (count $history) -ge $n
-            echo -- $history[$n]
-        else
-            echo -- $token
-        end
-    else
-        echo -- $token
-    end
-end

functions/expand_bang_search.fish

@@ -1,25 +0,0 @@
-# Execute expand_bang_search
-function expand_bang_search --description 'Execute expand_bang_search'
-    # Opinionated guard (C3): no expansion when overrides are disabled.
-    __fish_config_op_enabled __fish_config_op_overrides; or return 1
-
-    set -l token $argv[1]
-    if test -z "$token"
-        set token (commandline -t)
-    end
-    
-    # Extract query: looks for text after !? and before an optional ?
-    set -l query (string match -r '!\?([^?]+)' -- $token)[2]
-    
-    if test -n "$query"
-        # Search history for a match anywhere in the command
-        set -l match (builtin history search --contains --max=1 -- $query)
-        
-        if test -n "$match"
-            echo -- $match
-            return
-        end
-    end
-    
-    echo -- $token
-end

functions/expand_bang_string.fish

@@ -1,27 +0,0 @@
-# Execute expand_bang_string
-function expand_bang_string --description 'Execute expand_bang_string'
-    # Opinionated guard (C3): no expansion when overrides are disabled.
-    __fish_config_op_enabled __fish_config_op_overrides; or return 1
-
-    # Fish 4.x passes the matched token as argv[1]
-    set -l token $argv[1]
-    if test -z "$token"
-        set token (commandline -t)
-    end
-    
-    # Remove the '!' to get the search query
-    set -l query (string sub -s 2 -- $token)
-    
-    if test -n "$query"
-        # Search history for a prefix match
-        set -l match (builtin history search --prefix --max=1 -- $query)
-        
-        if test -n "$match"
-            echo -- $match
-            return
-        end
-    end
-    
-    # If no match or empty query, return the token so it doesn't vanish
-        echo -- $token
-end

functions/expand_typo_sub.fish

@@ -1,27 +0,0 @@
-# Execute expand_typo_sub
-function expand_typo_sub --description 'Execute expand_typo_sub'
-    # Opinionated guard (C3): no expansion when overrides are disabled.
-    __fish_config_op_enabled __fish_config_op_overrides; or return 1
-
-    # In newer Fish, the matched token is often passed as $argv[1]
-    # if the abbr is set up correctly. We'll fallback to commandline just in case.
-        set -l last_cmd $history[1]
-        set -l current_token $argv[1]
-        if test -z "$current_token"
-                set current_token (commandline -t)
-        end
-    
-        if string match -qr '\^([^^]+)\^([^^]*)' -- "$current_token"
-                set -l captured (string match -r '\^([^^]+)\^([^^]*)' -- "$current_token")
-                set -l old $captured[2]
-                set -l new $captured[3]
-        
-                if test -n "$old"
-                        # Using -- to ensure strings starting with '-' aren't treated as flags
-            echo -- (string replace -a -- "$old" "$new" "$last_cmd")
-        end
-    else
-        # Return the token itself so it doesn't vanish
-                echo -- "$current_token"
-        end
-end