Merge pull request 'docs: dynamic abbreviations with markdown tables' (#99) from feature/dynamic-abbreviations-docs into main

Reviewed-on: #99

.gitea/workflows/docs-drift.yml

@@ -1,45 +0,0 @@
-name: Offline docs drift reminder
-
-on:
-  push:
-    branches:
-      - main
-    paths:
-      - "README.md"
-
-jobs:
-  remind:
-    runs-on: racknerd-mini
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 2
-
-      - name: Check whether offline doc changed in same push
-        id: drift
-        run: |
-          if git diff --name-only HEAD~1 HEAD | grep -q '^docs/fish-config\.md$'; then
-            echo "synced=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "synced=false" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Open drift reminder issue
-        if: steps.drift.outputs.synced == 'false'
-        env:
-          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
-          SERVER_URL: ${{ github.server_url }}
-          REPO: ${{ github.repository }}
-          SHA: ${{ github.sha }}
-          BRANCH: ${{ github.ref_name }}
-        run: |
-          curl -s -X POST \
-            -H "Authorization: token ${GITEA_TOKEN}" \
-            -H "Content-Type: application/json" \
-            "${SERVER_URL}/api/v1/repos/${REPO}/issues" \
-            -d "{
-              \"title\": \"docs: README updated — review docs/fish-config.md for drift\",
-              \"body\": \"README.md was modified in commit ${SHA} but \`docs/fish-config.md\` (the offline manual) was not updated in the same push.\n\nPlease review the README diff and update the offline documentation if any functions, keybindings, abbreviations, or configuration options were added, removed, or changed.\n\nCommit: ${SHA}\nBranch: ${BRANCH}\",
-              \"labels\": [\"Kind/Documentation\"]
-            }"

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,30 @@ 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"]
+            
+            # Left-pad description to ensure at least 2 spaces for cell split
+            name_part = name.ljust(16)
+            if len(name_part) < len(name) + 2:
+                name_part = name + "  "
+                
+            lines_cat.append(f"    {name_part}{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,8 +101,12 @@ def build_concat(root: Path) -> str:
         chunks.append("#" * (depth + 1) + " " + heading)
         if _is_function_page(path, root):
             body = _with_entries(body, path, entries)
+        elif "04-abbreviations" in path.parts:
+            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"<CardGrid.*?</CardGrid>\n*", "", body, flags=re.DOTALL)
             body = re.sub(r"\[([^\]]+)\]\(/[^)]+\)", r"\1", body)
             chunks.append(mt.shift_headings(body, depth))
     return "\n\n".join(chunks) + "\n"
@@ -675,6 +703,9 @@ def build_site(root: Path, out: Path) -> list[dict]:
 
         if not is_function_dir:
             target = out / rel
+            if "04-abbreviations" in path.parts:
+                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

@@ -362,32 +362,40 @@ are active in Insert, Normal, and Visual modes unless noted.
 Abbreviations expand when you press Space or Enter. They are terminal-aware:
 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
     cdnvn           cd ~/.config/nvim; nvim
+    k               kate
+    e               edit
+    se              sudoedit
 
 ## 4.2 Navigation and Listing
 
+    Abbreviation  Description
+    ───────────────────────────────────────────────────────────────────
     l               ls
     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
+    Abbreviation  Description
+    ───────────────────────────────────────────────────────────────────
     lg              lazygit
-    gitig / git-ignore gi        (generate .gitignore)
+    g               git
+    gitig           generate .gitignore
+    git-ignore      generate .gitignore
 
 ## 4.4 Terminal Windows, Tabs, and Panes
 
@@ -395,6 +403,11 @@ 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`.
 
+    Abbreviation  Description
+    ───────────────────────────────────────────────────────────────────
+    editt           Open new tab with nvim (terminal-aware)
+    :q              Close current pane/window
+    :Q              Close current tab
     :w              New OS window
     :wv             Split pane horizontally (new pane below)
     :wh             Split pane vertically (new pane to the right)
@@ -406,141 +419,167 @@ variant and a WezTerm variant; the correct one is inserted based on
     :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
+    :tgcz           New tab at ~/.local/share/chezmoi
-    :tgcm   New tab at chezmoi source dir
+    :tgcm           New tab at ~/.config/chezmoi
     :tgp            New tab at ~/projects
     :tgr            New tab at / (root)
-
+    :wgk            New OS window at ~/.config/kitty
-Prefixes :wg* and :wvg* / :whg* open OS windows or splits to the same
+    :wgn            New OS window at ~/.config/nvim
-set of dirs, respectively.
+    :wgf            New OS window at ~/.config/fish
-
+    :wgh            New OS window at ~
-Prefixes :cd* open tabs with a quick cd shortcut:
+    :wgzd           New OS window at ~/.local/share/chezmoi
-
+    :wgcz           New OS window at ~/.config/chezmoi
+    :wgp            New OS window at ~/projects
+    :wgr            New OS window at / (root)
+    :wvgk           Split bottom at ~/.config/kitty
+    :wvgn           Split bottom at ~/.config/nvim
+    :wvgf           Split bottom at ~/.config/fish
+    :wvgh           Split bottom at ~
+    :wvgcz          Split bottom at ~/.local/share/chezmoi
+    :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 ~
-    :cdcz   cd to chezmoi source
+    :cdhn           cd ~; nvim
-    :cdp    cd ~/projects
+    :cdcz           cd ~/.local/share/chezmoi
-
+    :cdczn          cd ~/.local/share/chezmoi; nvim
-Appending n to any :cd* abbreviation also runs nvim after changing dir.
+    :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
 
+    Abbreviation  Description
+    ───────────────────────────────────────────────────────────────────
     dcl             docker context use default
-    dcls        docker context ls
     lzd             ld (lazydocker)
+    dcls            docker context ls
 
 ## 4.7 Systemctl
 
+    Abbreviation  Description
+    ───────────────────────────────────────────────────────────────────
     sc              systemctl
     ssc             sudo systemctl
     scu             systemctl --user
     st              systemctl status
-    scs         sudo systemctl start
+    scs             systemctl start
-    scr         sudo systemctl restart
+    scr             systemctl restart
-    ssct        sudo systemctl start
+    ssct            sudo systemctl status
-    sscs        sudo systemctl stop
+    sscs            sudo systemctl start
     sscr            sudo systemctl restart
 
 ## 4.8 AI Assistants
 
-    ag          agy
+    Abbreviation  Description
-    ag.         agy .
+    ───────────────────────────────────────────────────────────────────
     v               antigravity-ide
     s               wezterm ssh (WezTerm only)
+    ag              agy
+    ag.             agy .
 
 ## 4.9 History Expansion
 
-These are implemented as keybinding helpers, but can also be typed:
+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.
 
-    !^          Expand to first argument of previous command
+    Abbreviation  Description
-    !*          Expand to all arguments of previous command
+    ───────────────────────────────────────────────────────────────────
-    typo_sub    Interactive typo substitution (Ctrl+F)
+    !^              Expand to the first argument of the previous command
-    bang_string !string expansion
+    !*              Expand to all arguments of the previous command
-    bang_search !?string search
+    ^old^new^       Interactive typo substitution (replace 'old' with 'new' in previous command)
-    bang_minus_n  !-n  (nth-previous command)
+    !string         Expand to the most recent command starting with 'string'
+    !?string?       Expand to the most recent command containing 'string'
+    !-n             Expand to the nth-previous command
+    !!              Expand to the previous command
+    !$              Expand to the last argument of the previous command
+    !.              Expand .. to ../.. and so on
 
 ## 4.10 Miscellaneous
 
-    /exit       exit
+    Abbreviation  Description
-    :q          Close pane (alias for terminal close)
+    ───────────────────────────────────────────────────────────────────
-    :Q          Close tab
     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
 
 ## 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
-### Color Overrides
+    vdir            vdir --color=auto
-
-Force color output for common tools:
-
     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
-
+    tarnow          tar -acf
-### Archives and Networking
+    untar           tar -zxvf
-
+    tb              nc termbin.com 9999
-    tarnow  tar -acf              Create compressed archive (auto-detects format)
+    jctl            journalctl -p 3 -xb
-    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
 

docs/manual/04-abbreviations.md

@@ -1,193 +0,0 @@
----
-title: Abbreviations
-manTitle: 4. ABBREVIATIONS
-sidebar:
-  order: 8
-helpKeywords:
-- abbreviations
-- abbr
-- abbrs
----
-
-Abbreviations expand when you press Space or Enter. They are terminal-aware:
-some expand differently in Kitty vs WezTerm vs other terminals.
-
-## 4.1 Editors
-
-    n / nv / neovim    nvim
-    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
-    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
-    lg                 lazygit
-    gitig / git-ignore gi        (generate .gitignore)
-
-## 4.4 Terminal Windows, Tabs, and Panes
-
-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
-    :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 /
-    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
-    dcls        docker context ls
-    lzd         ld (lazydocker)
-
-## 4.7 Systemctl
-
-    sc          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
-    ag.         agy .
-    v           antigravity-ide
-    s           wezterm ssh (WezTerm only)
-
-## 4.9 History Expansion
-
-These are implemented as keybinding helpers, but can also be typed:
-
-    !^          Expand to first argument of previous command
-    !*          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
-
-    ..      cd ..
-    ...     cd ../..
-    ....    cd ../../..
-    .....   cd ../../../..
-    ......  cd ../../../../..
-
-### Color Overrides
-
-Force color output for common tools:
-
-    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/manual/04-abbreviations/01-editors.md

@@ -0,0 +1,6 @@
+---
+title: Editors
+manTitle: 4.1 Editors
+---
+
+<!-- GENERATED: Editors -->

docs/manual/04-abbreviations/02-navigation-and-listing.md

@@ -0,0 +1,6 @@
+---
+title: Navigation and Listing
+manTitle: 4.2 Navigation and Listing
+---
+
+<!-- GENERATED: Navigation and Listing -->

docs/manual/04-abbreviations/03-git.md

@@ -0,0 +1,6 @@
+---
+title: Git
+manTitle: 4.3 Git
+---
+
+<!-- GENERATED: Git -->

docs/manual/04-abbreviations/04-terminal-windows-tabs-and-panes.md

@@ -0,0 +1,10 @@
+---
+title: Terminal Windows, Tabs, and Panes
+manTitle: 4.4 Terminal Windows, Tabs, and Panes
+---
+
+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`.
+
+<!-- GENERATED: Terminal Windows, Tabs, and Panes -->

docs/manual/04-abbreviations/05-chezmoi.md

@@ -0,0 +1,6 @@
+---
+title: Chezmoi
+manTitle: 4.5 Chezmoi
+---
+
+<!-- GENERATED: Chezmoi -->

docs/manual/04-abbreviations/06-docker.md

@@ -0,0 +1,6 @@
+---
+title: Docker
+manTitle: 4.6 Docker
+---
+
+<!-- GENERATED: Docker -->

docs/manual/04-abbreviations/07-systemctl.md

@@ -0,0 +1,6 @@
+---
+title: Systemctl
+manTitle: 4.7 Systemctl
+---
+
+<!-- GENERATED: Systemctl -->

docs/manual/04-abbreviations/08-ai-assistants.md

@@ -0,0 +1,6 @@
+---
+title: AI Assistants
+manTitle: 4.8 AI Assistants
+---
+
+<!-- GENERATED: AI Assistants -->

docs/manual/04-abbreviations/09-history-expansion.md

@@ -0,0 +1,10 @@
+---
+title: History Expansion
+manTitle: 4.9 History Expansion
+---
+
+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.
+
+<!-- GENERATED: History Expansion -->

docs/manual/04-abbreviations/10-miscellaneous.md

@@ -0,0 +1,6 @@
+---
+title: Miscellaneous
+manTitle: 4.10 Miscellaneous
+---
+
+<!-- GENERATED: Miscellaneous -->

docs/manual/04-abbreviations/11-shell-aliases.md

@@ -0,0 +1,9 @@
+---
+title: Shell Aliases
+manTitle: 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.
+
+<!-- GENERATED: Shell Aliases -->

docs/manual/04-abbreviations/index.md

@@ -0,0 +1,27 @@
+---
+title: Abbreviations
+manTitle: 4. ABBREVIATIONS
+sidebar:
+  order: 8
+helpKeywords:
+- abbreviations
+- abbr
+- abbrs
+---
+
+Abbreviations expand when you press Space or Enter. They are terminal-aware:
+some expand differently in Kitty vs WezTerm vs other terminals.
+
+<CardGrid>
+  <LinkCard title="Editors" href="/04-abbreviations/01-editors/" />
+  <LinkCard title="Navigation and Listing" href="/04-abbreviations/02-navigation-and-listing/" />
+  <LinkCard title="Git" href="/04-abbreviations/03-git/" />
+  <LinkCard title="Terminal Windows, Tabs, and Panes" href="/04-abbreviations/04-terminal-windows-tabs-and-panes/" />
+  <LinkCard title="Chezmoi" href="/04-abbreviations/05-chezmoi/" />
+  <LinkCard title="Docker" href="/04-abbreviations/06-docker/" />
+  <LinkCard title="Systemctl" href="/04-abbreviations/07-systemctl/" />
+  <LinkCard title="AI Assistants" href="/04-abbreviations/08-ai-assistants/" />
+  <LinkCard title="History Expansion" href="/04-abbreviations/09-history-expansion/" />
+  <LinkCard title="Miscellaneous" href="/04-abbreviations/10-miscellaneous/" />
+  <LinkCard title="Shell Aliases" href="/04-abbreviations/11-shell-aliases/" />
+</CardGrid>

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