From ce84db593c0ee1eb7df18fb857c585cd084e5f0a Mon Sep 17 00:00:00 2001
From: rootiest <chris@rootiest.com>
Date: Wed, 10 Jun 2026 11:28:43 -0400
Subject: [PATCH 1/4] feat(guards): add opinionated component guards to
 config.fish and conf.d

Adds __fish_config_op_enabled helper (master __fish_config_opinionated
evaluated first via __fish_variable_check, then the category variable)
and gates C1-C4 components: CachyOS surgical override, PAGER/MANPAGER,
CDPATH, Vi mode, exit override, bang-bang bindings, history/cp/mv/wget/
grep aliases, cd->z alias, Fisher bootstrap and theme apply, paru/yay
wrapper generation, WakaTime hook, custom key chords, puffer, autopair,
starship prompt, Catppuccin colors, FZF_DEFAULT_OPTS, done notifications,
and Kitty/WezTerm window-management abbreviations.
---
 conf.d/abbr.fish                        | 371 ++++++++++++------------
 conf.d/autopair.fish                    |   4 +
 conf.d/done.fish                        |   4 +
 conf.d/first_run.fish                   |   8 +
 conf.d/key_bindings.fish                |   4 +
 conf.d/paru-wrapper.fish                |   4 +
 conf.d/puffer.fish                      |   5 +
 conf.d/starship.fish                    |   3 +
 conf.d/theme.fish                       |  10 +
 conf.d/tricks.fish                      |  86 +++---
 conf.d/wakatime.fish                    |   6 +
 conf.d/yay-wrapper.fish                 |   4 +
 conf.d/zoxide.fish                      |   6 +-
 config.fish                             |  57 +++-
 functions/__fish_config_op_enabled.fish |  46 +++
 15 files changed, 386 insertions(+), 232 deletions(-)
 create mode 100644 functions/__fish_config_op_enabled.fish

diff --git a/conf.d/abbr.fish b/conf.d/abbr.fish
index 02789f2..be6c762 100644
--- a/conf.d/abbr.fish
+++ b/conf.d/abbr.fish
@@ -76,13 +76,16 @@ abbr -a ag antigravity
 abbr -a ag. antigravity .
 # Quit
 abbr -a /exit exit
-if test "$TERM" = xterm-kitty
-    abbr -a :q kitty @ close-window # Kitty (Closes the active split/pane)
-    abbr -a :Q kitty @ close-tab # Kitty (Closes the whole tab)
-end
-if test "$TERM_PROGRAM" = WezTerm
-    abbr -a :q wezterm cli kill-pane # WezTerm
-    abbr -a :Q wezterm cli kill-pane # WezTerm
+# Window-management abbreviations are opinionated (C4 integrations)
+if __fish_config_op_enabled __fish_config_op_integrations
+    if test "$TERM" = xterm-kitty
+        abbr -a :q kitty @ close-window # Kitty (Closes the active split/pane)
+        abbr -a :Q kitty @ close-tab # Kitty (Closes the whole tab)
+    end
+    if test "$TERM_PROGRAM" = WezTerm
+        abbr -a :q wezterm cli kill-pane # WezTerm
+        abbr -a :Q wezterm cli kill-pane # WezTerm
+    end
 end
 
 ######### Alternates ##########
@@ -103,184 +106,188 @@ abbr -a lsT lstree
 # Speedtest using fast.com
 abbr -a speedtest-fast fast-cli
 
-# Window Creation (OS Windows)
-if test "$TERM" = xterm-kitty
-    abbr -a :w kitty @ launch --type=os-window # Kitty
-end
-if test "$TERM_PROGRAM" = WezTerm
-    abbr -a :w wezterm cli spawn --new-window # WezTerm
-end
+# Kitty/WezTerm window-management abbreviations are opinionated (C4
+# integrations): they assume an active Kitty or WezTerm session.
+if __fish_config_op_enabled __fish_config_op_integrations
+    # Window Creation (OS Windows)
+    if test "$TERM" = xterm-kitty
+        abbr -a :w kitty @ launch --type=os-window # Kitty
+    end
+    if test "$TERM_PROGRAM" = WezTerm
+        abbr -a :w wezterm cli spawn --new-window # WezTerm
+    end
 
-# Window Splits (Panes)
-if test "$TERM" = xterm-kitty
-    abbr -a :wv kitty @ launch --location=hsplit # Kitty (Horizontal split)
-    abbr -a :wh kitty @ launch --location=vsplit # Kitty (Vertical split)
-end
-if test "$TERM_PROGRAM" = WezTerm
-    abbr -a :wv wezterm cli split-pane --bottom # WezTerm
-    abbr -a :wh wezterm cli split-pane --right # WezTerm
-end
+    # Window Splits (Panes)
+    if test "$TERM" = xterm-kitty
+        abbr -a :wv kitty @ launch --location=hsplit # Kitty (Horizontal split)
+        abbr -a :wh kitty @ launch --location=vsplit # Kitty (Vertical split)
+    end
+    if test "$TERM_PROGRAM" = WezTerm
+        abbr -a :wv wezterm cli split-pane --bottom # WezTerm
+        abbr -a :wh wezterm cli split-pane --right # WezTerm
+    end
 
-# Window Detach (Move Pane)
-if test "$TERM" = xterm-kitty
-    abbr -a :wo kitty @ detach-window --target-tab=new # Kitty (Moves pane to new tab)
-    abbr -a :wot kitty @ detach-window # Kitty (Same as above, default behavior)
-end
-if test "$TERM_PROGRAM" = WezTerm
-    abbr -a :wo wezterm cli move-pane-to-new-tab --new-window # WezTerm
-    abbr -a :wot wezterm cli move-pane-to-new-tab # WezTerm
-end
+    # Window Detach (Move Pane)
+    if test "$TERM" = xterm-kitty
+        abbr -a :wo kitty @ detach-window --target-tab=new # Kitty (Moves pane to new tab)
+        abbr -a :wot kitty @ detach-window # Kitty (Same as above, default behavior)
+    end
+    if test "$TERM_PROGRAM" = WezTerm
+        abbr -a :wo wezterm cli move-pane-to-new-tab --new-window # WezTerm
+        abbr -a :wot wezterm cli move-pane-to-new-tab # WezTerm
+    end
 
-# Tab Creation
-if test "$TERM" = xterm-kitty
-    abbr -a :t kitty @ launch --type=tab # Kitty
-end
-if test "$TERM_PROGRAM" = WezTerm
-    abbr -a :t wezterm cli spawn # WezTerm
-end
+    # Tab Creation
+    if test "$TERM" = xterm-kitty
+        abbr -a :t kitty @ launch --type=tab # Kitty
+    end
+    if test "$TERM_PROGRAM" = WezTerm
+        abbr -a :t wezterm cli spawn # WezTerm
+    end
 
-# Rename Tab
-if test "$TERM" = xterm-kitty
-    abbr -a :tl "kitty @ set-tab-title" # Kitty -> Usage: :tl "New Title"
-end
-if test "$TERM_PROGRAM" = WezTerm
-    abbr -a :tl wezterm cli set-tab-title # WezTerm
-end
+    # Rename Tab
+    if test "$TERM" = xterm-kitty
+        abbr -a :tl "kitty @ set-tab-title" # Kitty -> Usage: :tl "New Title"
+    end
+    if test "$TERM_PROGRAM" = WezTerm
+        abbr -a :tl wezterm cli set-tab-title # WezTerm
+    end
 
-# Rename Window
-if test "$TERM" = xterm-kitty
-    abbr -a :tw "kitty @ set-window-title" # Kitty
-end
-if test "$TERM_PROGRAM" = WezTerm
-    abbr -a :tw wezterm cli set-window-title # WezTerm
-end
+    # Rename Window
+    if test "$TERM" = xterm-kitty
+        abbr -a :tw "kitty @ set-window-title" # Kitty
+    end
+    if test "$TERM_PROGRAM" = WezTerm
+        abbr -a :tw wezterm cli set-window-title # WezTerm
+    end
 
-# Rename Workspace
-if test "$TERM_PROGRAM" = WezTerm
-    abbr -a :twk wezterm cli rename-workspace # WezTerm
-end
-# Kitty does not have a direct CLI equivalent for renaming a dynamic "workspace" session.
+    # Rename Workspace
+    if test "$TERM_PROGRAM" = WezTerm
+        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
-    abbr -a :tp "kitty @ focus-tab --match neighbor:left" # Kitty
-    abbr -a :tn "kitty @ focus-tab --match neighbor:right" # Kitty
-end
-if test "$TERM_PROGRAM" = WezTerm
-    abbr -a :tp wezterm cli activate-tab --tab-relative -1 # WezTerm
-    abbr -a :tn wezterm cli activate-tab --tab-relative 1 # WezTerm
-end
+    # Tab Navigation
+    if test "$TERM" = xterm-kitty
+        abbr -a :tp "kitty @ focus-tab --match neighbor:left" # Kitty
+        abbr -a :tn "kitty @ focus-tab --match neighbor:right" # Kitty
+    end
+    if test "$TERM_PROGRAM" = WezTerm
+        abbr -a :tp wezterm cli activate-tab --tab-relative -1 # WezTerm
+        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
-    abbr -a :tgk kitty @ launch --type=tab --cwd ~/.config/kitty # Kitty
-    abbr -a :tgn kitty @ launch --type=tab --cwd ~/.config/nvim # Kitty
-    abbr -a :tgf kitty @ launch --type=tab --cwd ~/.config/fish # Kitty
-    abbr -a :tgh kitty @ launch --type=tab --cwd ~
-    abbr -a :tgcz kitty @ launch --type=tab --cwd ~/.local/share/chezmoi # Kitty
-    abbr -a :tgcm kitty @ launch --type=tab --cwd ~/.config/chezmoi # Kitty
-    abbr -a :tgp kitty @ launch --type=tab --cwd ~/projects # Kitty
-    abbr -a :tgr kitty @ launch --type=tab -- sudo -i
-end
-if test "$TERM_PROGRAM" = WezTerm
-    abbr -a :tgk wezterm cli spawn --cwd ~/.config/kitty # WezTerm
-    abbr -a :tgn wezterm cli spawn --cwd ~/.config/nvim # WezTerm
-    abbr -a :tgf wezterm cli spawn --cwd ~/.config/fish # WezTerm
-    abbr -a :tgh wezterm cli spawn --cwd ~ # WezTerm
-    abbr -a :tgcz wezterm cli spawn --cwd ~/.local/share/chezmoi # WezTerm
-    abbr -a :tgcm wezterm cli spawn --cwd ~/.config/chezmoi # WezTerm
-    abbr -a :tgp wezterm cli spawn --cwd ~/projects # WezTerm
-    abbr -a :tgr wezterm cli spawn -- sudo -i # WezTerm
-end
+    # Specialty Tab Shortcuts (New Tab in specific dir)
+    if test "$TERM" = xterm-kitty
+        abbr -a :tgk kitty @ launch --type=tab --cwd ~/.config/kitty # Kitty
+        abbr -a :tgn kitty @ launch --type=tab --cwd ~/.config/nvim # Kitty
+        abbr -a :tgf kitty @ launch --type=tab --cwd ~/.config/fish # Kitty
+        abbr -a :tgh kitty @ launch --type=tab --cwd ~
+        abbr -a :tgcz kitty @ launch --type=tab --cwd ~/.local/share/chezmoi # Kitty
+        abbr -a :tgcm kitty @ launch --type=tab --cwd ~/.config/chezmoi # Kitty
+        abbr -a :tgp kitty @ launch --type=tab --cwd ~/projects # Kitty
+        abbr -a :tgr kitty @ launch --type=tab -- sudo -i
+    end
+    if test "$TERM_PROGRAM" = WezTerm
+        abbr -a :tgk wezterm cli spawn --cwd ~/.config/kitty # WezTerm
+        abbr -a :tgn wezterm cli spawn --cwd ~/.config/nvim # WezTerm
+        abbr -a :tgf wezterm cli spawn --cwd ~/.config/fish # WezTerm
+        abbr -a :tgh wezterm cli spawn --cwd ~ # WezTerm
+        abbr -a :tgcz wezterm cli spawn --cwd ~/.local/share/chezmoi # WezTerm
+        abbr -a :tgcm wezterm cli spawn --cwd ~/.config/chezmoi # WezTerm
+        abbr -a :tgp wezterm cli spawn --cwd ~/projects # WezTerm
+        abbr -a :tgr wezterm cli spawn -- sudo -i # WezTerm
+    end
 
-# Specialty Window Shortcuts (New OS Window in specific dir)
-if test "$TERM" = xterm-kitty
-    abbr -a :wgk kitty @ launch --type=os-window --cwd ~/.config/kitty # Kitty
-    abbr -a :wgn kitty @ launch --type=os-window --cwd ~/.config/nvim # Kitty
-    abbr -a :wgf kitty @ launch --type=os-window --cwd ~/.config/fish # Kitty
-    abbr -a :wgh kitty @ launch --type=os-window --cwd ~
-    abbr -a :wgzd kitty @ launch --type=os-window --cwd ~/.local/share/chezmoi # Kitty
-    abbr -a :wgcz kitty @ launch --type=os-window --cwd ~/.config/chezmoi # Kitty
-    abbr -a :wgp kitty @ launch --type=os-window --cwd ~/projects # Kitty
-    abbr -a :wgr kitty @ launch --type=os-window -- sudo -i # Kitty
-end
-if test "$TERM_PROGRAM" = WezTerm
-    abbr -a :wgk wezterm cli spawn --new-window --cwd ~/.config/kitty # WezTerm
-    abbr -a :wgn wezterm cli spawn --new-window --cwd ~/.config/nvim # WezTerm
-    abbr -a :wgf wezterm cli spawn --new-window --cwd ~/.config/fish # WezTerm
-    abbr -a :wgh wezterm cli spawn --new-window --cwd ~ # WezTerm
-    abbr -a :wgzd wezterm cli spawn --new-window --cwd ~/.local/share/chezmoi # WezTerm
-    abbr -a :wgcz wezterm cli spawn --new-window --cwd ~/.config/chezmoi # WezTerm
-    abbr -a :wgp wezterm cli spawn --new-window --cwd ~/projects # WezTerm
-    abbr -a :wgr wezterm cli spawn --new-window -- sudo -i # WezTerm
-end
+    # Specialty Window Shortcuts (New OS Window in specific dir)
+    if test "$TERM" = xterm-kitty
+        abbr -a :wgk kitty @ launch --type=os-window --cwd ~/.config/kitty # Kitty
+        abbr -a :wgn kitty @ launch --type=os-window --cwd ~/.config/nvim # Kitty
+        abbr -a :wgf kitty @ launch --type=os-window --cwd ~/.config/fish # Kitty
+        abbr -a :wgh kitty @ launch --type=os-window --cwd ~
+        abbr -a :wgzd kitty @ launch --type=os-window --cwd ~/.local/share/chezmoi # Kitty
+        abbr -a :wgcz kitty @ launch --type=os-window --cwd ~/.config/chezmoi # Kitty
+        abbr -a :wgp kitty @ launch --type=os-window --cwd ~/projects # Kitty
+        abbr -a :wgr kitty @ launch --type=os-window -- sudo -i # Kitty
+    end
+    if test "$TERM_PROGRAM" = WezTerm
+        abbr -a :wgk wezterm cli spawn --new-window --cwd ~/.config/kitty # WezTerm
+        abbr -a :wgn wezterm cli spawn --new-window --cwd ~/.config/nvim # WezTerm
+        abbr -a :wgf wezterm cli spawn --new-window --cwd ~/.config/fish # WezTerm
+        abbr -a :wgh wezterm cli spawn --new-window --cwd ~ # WezTerm
+        abbr -a :wgzd wezterm cli spawn --new-window --cwd ~/.local/share/chezmoi # WezTerm
+        abbr -a :wgcz wezterm cli spawn --new-window --cwd ~/.config/chezmoi # WezTerm
+        abbr -a :wgp wezterm cli spawn --new-window --cwd ~/projects # WezTerm
+        abbr -a :wgr wezterm cli spawn --new-window -- sudo -i # WezTerm
+    end
 
-# Specialty Window Vertical Shortcuts (Split Bottom)
-if test "$TERM" = xterm-kitty
-    abbr -a :wvgk kitty @ launch --location=hsplit --cwd ~/.config/kitty # Kitty
-    abbr -a :wvgn kitty @ launch --location=hsplit --cwd ~/.config/nvim # Kitty
-    abbr -a :wvgf kitty @ launch --location=hsplit --cwd ~/.config/fish # Kitty
-    abbr -a :wvgh kitty @ launch --location=hsplit --cwd ~ # Kitty
-    abbr -a :wvgcz kitty @ launch --location=hsplit --cwd ~/.local/share/chezmoi # Kitty
-    abbr -a :wvgcm kitty @ launch --location=hsplit --cwd ~/.config/chezmoi # Kitty
-    abbr -a :wvgp kitty @ launch --location=hsplit --cwd ~/projects # Kitty
-    abbr -a :wvgr kitty @ launch --location=hsplit -- sudo -i # Kitty
-end
-if test "$TERM_PROGRAM" = WezTerm
-    abbr -a :wvgk wezterm cli split-pane --bottom --cwd ~/.config/kitty # WezTerm
-    abbr -a :wvgn wezterm cli split-pane --bottom --cwd ~/.config/nvim # WezTerm
-    abbr -a :wvgf wezterm cli split-pane --bottom --cwd ~/.config/fish # WezTerm
-    abbr -a :wvgh wezterm cli split-pane --bottom --cwd ~ # WezTerm
-    abbr -a :wvgcz wezterm cli split-pane --bottom --cwd ~/.local/share/chezmoi # WezTerm
-    abbr -a :wvgcm wezterm cli split-pane --bottom --cwd ~/.config/chezmoi # WezTerm
-    abbr -a :wvgp wezterm cli split-pane --bottom --cwd ~/projects # WezTerm
-    abbr -a :wvgr wezterm cli split-pane --bottom -- sudo -i # WezTerm
-end
+    # Specialty Window Vertical Shortcuts (Split Bottom)
+    if test "$TERM" = xterm-kitty
+        abbr -a :wvgk kitty @ launch --location=hsplit --cwd ~/.config/kitty # Kitty
+        abbr -a :wvgn kitty @ launch --location=hsplit --cwd ~/.config/nvim # Kitty
+        abbr -a :wvgf kitty @ launch --location=hsplit --cwd ~/.config/fish # Kitty
+        abbr -a :wvgh kitty @ launch --location=hsplit --cwd ~ # Kitty
+        abbr -a :wvgcz kitty @ launch --location=hsplit --cwd ~/.local/share/chezmoi # Kitty
+        abbr -a :wvgcm kitty @ launch --location=hsplit --cwd ~/.config/chezmoi # Kitty
+        abbr -a :wvgp kitty @ launch --location=hsplit --cwd ~/projects # Kitty
+        abbr -a :wvgr kitty @ launch --location=hsplit -- sudo -i # Kitty
+    end
+    if test "$TERM_PROGRAM" = WezTerm
+        abbr -a :wvgk wezterm cli split-pane --bottom --cwd ~/.config/kitty # WezTerm
+        abbr -a :wvgn wezterm cli split-pane --bottom --cwd ~/.config/nvim # WezTerm
+        abbr -a :wvgf wezterm cli split-pane --bottom --cwd ~/.config/fish # WezTerm
+        abbr -a :wvgh wezterm cli split-pane --bottom --cwd ~ # WezTerm
+        abbr -a :wvgcz wezterm cli split-pane --bottom --cwd ~/.local/share/chezmoi # WezTerm
+        abbr -a :wvgcm wezterm cli split-pane --bottom --cwd ~/.config/chezmoi # WezTerm
+        abbr -a :wvgp wezterm cli split-pane --bottom --cwd ~/projects # WezTerm
+        abbr -a :wvgr wezterm cli split-pane --bottom -- sudo -i # WezTerm
+    end
 
-# Specialty Window Horizontal Shortcuts (Split Right)
-if test "$TERM" = xterm-kitty
-    abbr -a :whgk kitty @ launch --location=vsplit --cwd ~/.config/kitty # Kitty
-    abbr -a :whgn kitty @ launch --location=vsplit --cwd ~/.config/nvim # Kitty
-    abbr -a :whgf kitty @ launch --location=vsplit --cwd ~/.config/fish # Kitty
-    abbr -a :whgh kitty @ launch --location=vsplit --cwd ~ # Kitty
-    abbr -a :whgcz kitty @ launch --location=vsplit --cwd ~/.local/share/chezmoi # Kitty
-    abbr -a :whgcm kitty @ launch --location=vsplit --cwd ~/.config/chezmoi # Kitty
-    abbr -a :whgp kitty @ launch --location=vsplit --cwd ~/projects # Kitty
-    abbr -a :whgr kitty @ launch --location=vsplit --cwd current sudo -i # Kitty -> Specialty cd Shortcuts
-    abbr -a :cdk 'cd ~/.config/kitty/ # Kitty Config'
-    abbr -a :cdkn 'cd ~/.config/kitty;nvim'
-end
-if test "$TERM_PROGRAM" = WezTerm
-    abbr -a :whgk wezterm cli split-pane --bottom --cwd ~/.config/kitty # WezTerm
-    abbr -a :whgn wezterm cli split-pane --bottom --cwd ~/.config/nvim # WezTerm
-    abbr -a :whgf wezterm cli split-pane --bottom --cwd ~/.config/fish # WezTerm
-    abbr -a :whgh wezterm cli split-pane --bottom --cwd ~ # WezTerm
-    abbr -a :whgcz wezterm cli split-pane --bottom --cwd ~/.local/share/chezmoi # WezTerm
-    abbr -a :whgcm wezterm cli split-pane --bottom --cwd ~/.config/chezmoi # WezTerm
-    abbr -a :whgp wezterm cli split-pane --bottom --cwd ~/projects # WezTerm
-    abbr -a :whgr wezterm cli split-pane --bottom -- sudo -i # WezTerm
-end
-abbr -a :cdn cd '~/.config/nvim/ # Neovim Config'
-abbr -a :cdnn 'cd ~/.config/nvim;nvim'
-abbr -a :cdf 'cd ~/.config/fish/ # Fish Config'
-abbr -a :cdfn 'cd ~/.config/fish;nvim'
-abbr -a :cdh 'cd ~ # Home Directory'
-abbr -a :cdhn 'cd ~;nvim'
-abbr -a :cdcz cd '~/.local/share/chezmoi/ # Chezmoi Source'
-abbr -a :cdczn 'cd ~/.local/share/chezmoi;nvim'
-abbr -a :cdcm 'cd ~/.config/chezmoi/ # Chezmoi Config'
-abbr -a :cdcmn 'cd ~/.config/chezmoi;nvim'
-abbr -a :cdp --regex ':cdp' --set-cursor 'cd ~/projects/%'
-# abbr -a cdp_slash --position anywhere --regex ':cdp/' --set-cursor 'cd ~/projects/%'
-abbr -a :cdpn 'cd ~/projects;nvim'
-abbr -a :cdw 'cd ~/.config/wezterm/ # WezTerm Config'
-abbr -a :cdwn 'cd ~/.config/wezterm;nvim'
-if test "$TERM" = xterm-kitty
-    abbr -a editt kitty @ launch --type tab nvim
-end
-# Spawn window
-if test "$TERM" = xterm-kitty
-    abbr -a :sw spwin
+    # Specialty Window Horizontal Shortcuts (Split Right)
+    if test "$TERM" = xterm-kitty
+        abbr -a :whgk kitty @ launch --location=vsplit --cwd ~/.config/kitty # Kitty
+        abbr -a :whgn kitty @ launch --location=vsplit --cwd ~/.config/nvim # Kitty
+        abbr -a :whgf kitty @ launch --location=vsplit --cwd ~/.config/fish # Kitty
+        abbr -a :whgh kitty @ launch --location=vsplit --cwd ~ # Kitty
+        abbr -a :whgcz kitty @ launch --location=vsplit --cwd ~/.local/share/chezmoi # Kitty
+        abbr -a :whgcm kitty @ launch --location=vsplit --cwd ~/.config/chezmoi # Kitty
+        abbr -a :whgp kitty @ launch --location=vsplit --cwd ~/projects # Kitty
+        abbr -a :whgr kitty @ launch --location=vsplit --cwd current sudo -i # Kitty -> Specialty cd Shortcuts
+        abbr -a :cdk 'cd ~/.config/kitty/ # Kitty Config'
+        abbr -a :cdkn 'cd ~/.config/kitty;nvim'
+    end
+    if test "$TERM_PROGRAM" = WezTerm
+        abbr -a :whgk wezterm cli split-pane --bottom --cwd ~/.config/kitty # WezTerm
+        abbr -a :whgn wezterm cli split-pane --bottom --cwd ~/.config/nvim # WezTerm
+        abbr -a :whgf wezterm cli split-pane --bottom --cwd ~/.config/fish # WezTerm
+        abbr -a :whgh wezterm cli split-pane --bottom --cwd ~ # WezTerm
+        abbr -a :whgcz wezterm cli split-pane --bottom --cwd ~/.local/share/chezmoi # WezTerm
+        abbr -a :whgcm wezterm cli split-pane --bottom --cwd ~/.config/chezmoi # WezTerm
+        abbr -a :whgp wezterm cli split-pane --bottom --cwd ~/projects # WezTerm
+        abbr -a :whgr wezterm cli split-pane --bottom -- sudo -i # WezTerm
+    end
+    abbr -a :cdn cd '~/.config/nvim/ # Neovim Config'
+    abbr -a :cdnn 'cd ~/.config/nvim;nvim'
+    abbr -a :cdf 'cd ~/.config/fish/ # Fish Config'
+    abbr -a :cdfn 'cd ~/.config/fish;nvim'
+    abbr -a :cdh 'cd ~ # Home Directory'
+    abbr -a :cdhn 'cd ~;nvim'
+    abbr -a :cdcz cd '~/.local/share/chezmoi/ # Chezmoi Source'
+    abbr -a :cdczn 'cd ~/.local/share/chezmoi;nvim'
+    abbr -a :cdcm 'cd ~/.config/chezmoi/ # Chezmoi Config'
+    abbr -a :cdcmn 'cd ~/.config/chezmoi;nvim'
+    abbr -a :cdp --regex ':cdp' --set-cursor 'cd ~/projects/%'
+    # abbr -a cdp_slash --position anywhere --regex ':cdp/' --set-cursor 'cd ~/projects/%'
+    abbr -a :cdpn 'cd ~/projects;nvim'
+    abbr -a :cdw 'cd ~/.config/wezterm/ # WezTerm Config'
+    abbr -a :cdwn 'cd ~/.config/wezterm;nvim'
+    if test "$TERM" = xterm-kitty
+        abbr -a editt kitty @ launch --type tab nvim
+    end
+    # Spawn window
+    if test "$TERM" = xterm-kitty
+        abbr -a :sw spwin
+    end
 end
 
 ### Docker ###
@@ -307,9 +314,13 @@ abbr -a sscs 'sudo systemctl start'
 abbr -a sscr 'sudo systemctl restart'
 
 ### History Expansions and Substitutions ###
-abbr -a !^ --position anywhere --function expand_bang_caret
-abbr -a '!*' --position anywhere --function expand_bang_all
-abbr -a typo_sub --position anywhere --regex '\^([^^]+)\^([^^]*)' --function expand_typo_sub
-abbr -a bang_string --position anywhere --regex '![\w.-]+' --function expand_bang_string
-abbr -a bang_search --position anywhere --regex '!\?[\w.-]+\??' --function expand_bang_search
-abbr -a bang_minus_n --position anywhere --regex '!-(\d+)' --function expand_bang_minus_n
+# 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
+    abbr -a !^ --position anywhere --function expand_bang_caret
+    abbr -a '!*' --position anywhere --function expand_bang_all
+    abbr -a typo_sub --position anywhere --regex '\^([^^]+)\^([^^]*)' --function expand_typo_sub
+    abbr -a bang_string --position anywhere --regex '![\w.-]+' --function expand_bang_string
+    abbr -a bang_search --position anywhere --regex '!\?[\w.-]+\??' --function expand_bang_search
+    abbr -a bang_minus_n --position anywhere --regex '!-(\d+)' --function expand_bang_minus_n
+end
diff --git a/conf.d/autopair.fish b/conf.d/autopair.fish
index abb4bf3..571457f 100644
--- a/conf.d/autopair.fish
+++ b/conf.d/autopair.fish
@@ -1,5 +1,9 @@
 status is-interactive || exit
 
+# Local modification: opinionated guard (AGENTS.md Task #3). Bracket
+# auto-pairing intercepts single-character input, classified as C3 overrides.
+__fish_config_op_enabled __fish_config_op_overrides || exit
+
 set --global autopair_left "(" "[" "{" '"' "'"
 set --global autopair_right ")" "]" "}" '"' "'"
 set --global autopair_pairs "()" "[]" "{}" '""' "''"
diff --git a/conf.d/done.fish b/conf.d/done.fish
index 9252660..bb108d0 100644
--- a/conf.d/done.fish
+++ b/conf.d/done.fish
@@ -24,6 +24,10 @@ if not status is-interactive
     exit
 end
 
+# Local modification: opinionated guard (AGENTS.md Task #3). Desktop
+# notifications assume a graphical session, classified as C4 integrations.
+__fish_config_op_enabled __fish_config_op_integrations; or exit
+
 set -g __done_version 1.19.1
 
 function __done_run_powershell_script
diff --git a/conf.d/first_run.fish b/conf.d/first_run.fish
index ef96983..958f03a 100644
--- a/conf.d/first_run.fish
+++ b/conf.d/first_run.fish
@@ -29,6 +29,14 @@ echo "  Run 'help config' for offline documentation."
 echo "  Run 'fish-deps'   to check and install dependencies."
 echo ""
 
+#   ─────────────────────── Opinionated auto-exec guard ────────────────────
+# Startup side-effects below (Fisher curl, fisher update, theme apply) are
+# opinionated (C2 auto-execution). The first-run state variable is already
+# set above either way, so disabling auto-exec never re-triggers this file.
+if not __fish_config_op_enabled __fish_config_op_autoexec
+    return
+end
+
 #   ──────────────────────────── Bootstrap Fisher ──────────────────────────
 if not type -q fisher
     echo "  [first-run] Installing Fisher plugin manager..."
diff --git a/conf.d/key_bindings.fish b/conf.d/key_bindings.fish
index 109f3ca..47aa799 100644
--- a/conf.d/key_bindings.fish
+++ b/conf.d/key_bindings.fish
@@ -46,6 +46,10 @@
 
 function fish_user_key_bindings
 
+    # Custom key chords are opinionated (C3 overrides); skip them entirely
+    # when overrides are disabled so stock bindings remain untouched.
+    __fish_config_op_enabled __fish_config_op_overrides; or return
+
     #   ───────────────────────────── Set Bindings ─────────────────────────────
     #
     # Set Emacs mode bindings:
diff --git a/conf.d/paru-wrapper.fish b/conf.d/paru-wrapper.fish
index b388062..da9db45 100644
--- a/conf.d/paru-wrapper.fish
+++ b/conf.d/paru-wrapper.fish
@@ -5,6 +5,10 @@
 # /usr/bin/paru is installed. The wrapper tees paru output to a
 # timestamped log file and prunes old logs, mirroring smart_exit behavior.
 
+# Auto-generating a wrapper in ~/.local/bin is opinionated (C2 auto-exec).
+# Task #4's __fish_config_enable_logging will additionally gate this wrapper.
+__fish_config_op_enabled __fish_config_op_autoexec; or return
+
 set -l _paru_real /usr/bin/paru
 set -l _paru_wrapper "$HOME/.local/bin/paru"
 set -l _paru_wrapper_version 1
diff --git a/conf.d/puffer.fish b/conf.d/puffer.fish
index 44ff6f0..a50fe03 100644
--- a/conf.d/puffer.fish
+++ b/conf.d/puffer.fish
@@ -1,5 +1,10 @@
 status is-interactive || exit
 
+# Local modification: opinionated guard (AGENTS.md Task #3). Puffer's key
+# intercepts are part of the bang-bang system, gated atomically under C3
+# overrides with conf.d/tricks.fish, conf.d/abbr.fish, and expand_*.fish.
+__fish_config_op_enabled __fish_config_op_overrides || exit
+
 function _puffer_fish_key_bindings --on-variable fish_key_bindings
     set -l modes
     if test "$fish_key_bindings" = fish_default_key_bindings
diff --git a/conf.d/starship.fish b/conf.d/starship.fish
index c0c250a..a7a429a 100644
--- a/conf.d/starship.fish
+++ b/conf.d/starship.fish
@@ -5,6 +5,9 @@
 # Without starship, fish's built-in prompt already emits OSC 133;A
 # on the prompt line itself, so no wrapper is needed.
 
+# Replacing the prompt is opinionated (C3 overrides)
+__fish_config_op_enabled __fish_config_op_overrides; or return
+
 type -q starship; or return
 
 function fish_prompt
diff --git a/conf.d/theme.fish b/conf.d/theme.fish
index 6cc0b07..1cd1f8a 100644
--- a/conf.d/theme.fish
+++ b/conf.d/theme.fish
@@ -6,6 +6,16 @@
 #          ╰──────────────────────────────────────────────────────────╯
 # Catppuccin Mocha
 
+# Forcing theme colors and $FZF_DEFAULT_OPTS is opinionated (C3 overrides).
+# The FZF variable is universal, so clean up our Catppuccin value if it
+# lingers from a session where overrides were still enabled.
+if not __fish_config_op_enabled __fish_config_op_overrides
+    if set -q FZF_DEFAULT_OPTS; and string match -q '*#1E1E2E*' -- "$FZF_DEFAULT_OPTS"
+        set --erase FZF_DEFAULT_OPTS
+    end
+    return
+end
+
 #   ────────────────────── Syntax highlighting colors ──────────────────────
 set --global fish_color_autosuggestion 6c7086
 set --global fish_color_cancel f38ba8
diff --git a/conf.d/tricks.fish b/conf.d/tricks.fish
index 1e48268..0191b20 100644
--- a/conf.d/tricks.fish
+++ b/conf.d/tricks.fish
@@ -29,7 +29,8 @@ if test -f $_src; and not test -L $_man1/fish-config.1
 end
 
 # Format man pages using bat (only if bat is installed)
-if type -q bat
+# Overriding $MANPAGER is opinionated (C3 overrides)
+if type -q bat; and __fish_config_op_enabled __fish_config_op_overrides
     set -gx MANROFFOPT -c
     set -gx MANPAGER "sh -c 'col -bx | bat -l man -p'"
 end
@@ -40,38 +41,46 @@ set -gx __done_notification_urgency_level low
 
 ## Functions
 # Functions needed for !! and !$ https://github.com/oh-my-fish/plugin-bang-bang
-function __history_previous_command
-    switch (commandline -t)
-        case "!"
-            commandline -t $history[1]
-            commandline -f repaint
-        case "*"
-            commandline -i !
+# The bang-bang system is opinionated (C3 overrides) and is gated atomically
+# here, in conf.d/abbr.fish, conf.d/puffer.fish, and functions/expand_*.fish.
+if __fish_config_op_enabled __fish_config_op_overrides
+    function __history_previous_command
+        switch (commandline -t)
+            case "!"
+                commandline -t $history[1]
+                commandline -f repaint
+            case "*"
+                commandline -i !
+        end
     end
-end
 
-function __history_previous_command_arguments
-    switch (commandline -t)
-        case "!"
-            commandline -t ""
-            commandline -f history-token-search-backward
-        case "*"
-            commandline -i '$'
+    function __history_previous_command_arguments
+        switch (commandline -t)
+            case "!"
+                commandline -t ""
+                commandline -f history-token-search-backward
+            case "*"
+                commandline -i '$'
+        end
     end
-end
 
-# Apply bang-bang key bindings based on current key binding mode
-if [ "$fish_key_bindings" = fish_vi_key_bindings ]
-    bind -Minsert ! __history_previous_command
-    bind -Minsert '$' __history_previous_command_arguments
-else
-    bind ! __history_previous_command
-    bind '$' __history_previous_command_arguments
+    # Apply bang-bang key bindings based on current key binding mode
+    if [ "$fish_key_bindings" = fish_vi_key_bindings ]
+        bind -Minsert ! __history_previous_command
+        bind -Minsert '$' __history_previous_command_arguments
+    else
+        bind ! __history_previous_command
+        bind '$' __history_previous_command_arguments
+    end
 end
 
 # Fish command history override to show timestamps
-function history
-    builtin history --show-time='%F %T '
+# Shadowing the history command is opinionated (C1 aliasing); when disabled,
+# the function is never defined and fish's stock history behavior applies.
+if __fish_config_op_enabled __fish_config_op_aliases
+    function history
+        builtin history --show-time='%F %T '
+    end
 end
 
 # Quick file backup utility
@@ -97,21 +106,26 @@ alias ....='cd ../../..'
 alias .....='cd ../../../..'
 alias ......='cd ../../../../..'
 
-# Tools & Core command color overrides
-alias dir='dir --color=auto'
-alias vdir='vdir --color=auto'
-alias grep='grep --color=auto'
-alias fgrep='fgrep --color=auto'
-alias egrep='egrep --color=auto'
+# Silent flag injection into POSIX tools is opinionated (C1 aliasing)
+if __fish_config_op_enabled __fish_config_op_aliases
+    # Tools & Core command color overrides
+    alias dir='dir --color=auto'
+    alias vdir='vdir --color=auto'
+    alias grep='grep --color=auto'
+    alias fgrep='fgrep --color=auto'
+    alias egrep='egrep --color=auto'
 
-# Safety aliases (Confirmation before overwriting/deleting)
-alias cp="cp -i"
-alias mv="mv -i"
+    # Safety aliases (Confirmation before overwriting/deleting)
+    alias cp="cp -i"
+    alias mv="mv -i"
+
+    # Force wget to resume partial downloads
+    alias wget='wget -c '
+end
 
 # Archives and networking short-hands
 alias tarnow='tar -acf '
 alias untar='tar -zxvf '
-alias wget='wget -c '
 alias tb='nc termbin.com 9999'
 
 # System Logs
diff --git a/conf.d/wakatime.fish b/conf.d/wakatime.fish
index bedd7e0..91c88f4 100644
--- a/conf.d/wakatime.fish
+++ b/conf.d/wakatime.fish
@@ -5,6 +5,12 @@
 # see: https://github.com/ik11235/wakatime.fish
 ###
 
+# Local modification: opinionated guard (AGENTS.md Task #3). WakaTime
+# reporting is classified under both C2 auto-execution and C4 integrations;
+# disabling either category skips registering the hook.
+__fish_config_op_enabled __fish_config_op_autoexec; or exit
+__fish_config_op_enabled __fish_config_op_integrations; or exit
+
 function __register_wakatime_fish_before_exec -e fish_postexec
   if set -q FISH_WAKATIME_DISABLED
     return 0
diff --git a/conf.d/yay-wrapper.fish b/conf.d/yay-wrapper.fish
index d4351c9..258f1ec 100644
--- a/conf.d/yay-wrapper.fish
+++ b/conf.d/yay-wrapper.fish
@@ -5,6 +5,10 @@
 # /usr/bin/yay is installed. The wrapper tees yay output to a
 # timestamped log file and prunes old logs, mirroring smart_exit behavior.
 
+# Auto-generating a wrapper in ~/.local/bin is opinionated (C2 auto-exec).
+# Task #4's __fish_config_enable_logging will additionally gate this wrapper.
+__fish_config_op_enabled __fish_config_op_autoexec; or return
+
 set -l _yay_real /usr/bin/yay
 set -l _yay_wrapper "$HOME/.local/bin/yay"
 set -l _yay_wrapper_version 1
diff --git a/conf.d/zoxide.fish b/conf.d/zoxide.fish
index e6eaaf7..57a6efe 100644
--- a/conf.d/zoxide.fish
+++ b/conf.d/zoxide.fish
@@ -63,7 +63,11 @@ if status is-interactive
 
         # -------------
 
-        alias cd=z
+        # Shadowing cd with zoxide is opinionated (C1 aliasing); z and zi
+        # remain available either way.
+        if __fish_config_op_enabled __fish_config_op_aliases
+            alias cd=z
+        end
 
         # use custom completion
         complete -c z -f # disable files by default 
diff --git a/config.fish b/config.fish
index 01a9b87..07acc3c 100644
--- a/config.fish
+++ b/config.fish
@@ -5,17 +5,32 @@
 #          │                    Fish Configuration                    │
 #          ╰──────────────────────────────────────────────────────────╯
 
+#   ───────────────────── Opinionated component guards ─────────────────────
+# Opinionated components (AGENTS.md Task #3) are wrapped in
+# __fish_config_op_enabled <category> guards throughout this file and conf.d/.
+# The helper always evaluates the master switch __fish_config_opinionated
+# first (falsy disables everything), then the per-category opt-out variable:
+#   __fish_config_op_aliases       C1 — command shadows / flag injection
+#   __fish_config_op_autoexec      C2 — startup side-effects
+#   __fish_config_op_overrides     C3 — key bindings, env, prompt overrides
+#   __fish_config_op_integrations  C4 — terminal/tool coupling
+# Example: set -U __fish_config_op_aliases off   (erase to re-enable)
+
 #   ──────────────────────── Source CachyOS configs ────────────────────────
 if test -f /usr/share/cachyos-fish-config/cachyos-config.fish
     source /usr/share/cachyos-fish-config/cachyos-config.fish
-    # Source our tricks over the cachyOS config
-    test -f "$__fish_config_dir/conf.d/tricks.fish"
-    and source "$__fish_config_dir/conf.d/tricks.fish"
-    # Erase CachyOS aliases/functions that shadow our versions, then
-    # re-source our versions since functions --erase removes autoload entries.
-    for _fname in ls lt cleanup copy
-        functions --erase $_fname
-        source "$__fish_config_dir/functions/$_fname.fish"
+    # Surgically overriding the distro config is opinionated (C3 overrides):
+    # skip it entirely when overrides are disabled, keeping CachyOS defaults.
+    if __fish_config_op_enabled __fish_config_op_overrides
+        # Source our tricks over the cachyOS config
+        test -f "$__fish_config_dir/conf.d/tricks.fish"
+        and source "$__fish_config_dir/conf.d/tricks.fish"
+        # Erase CachyOS aliases/functions that shadow our versions, then
+        # re-source our versions since functions --erase removes autoload entries.
+        for _fname in ls lt cleanup copy
+            functions --erase $_fname
+            source "$__fish_config_dir/functions/$_fname.fish"
+        end
     end
 end
 set --erase _fname
@@ -47,10 +62,13 @@ set -gx CODEIUM_HOME "$XDG_CONFIG_HOME/codeium"
 set -gx WORDLIST "$XDG_CONFIG_HOME/hunspell_en_US"
 
 #   ─────────────────────────── Pager variables ────────────────────────────
-if type -q ov
-    set -gx PAGER ov
-else if type -q less
-    set -gx PAGER less
+# Overriding $PAGER is opinionated (C3 overrides)
+if __fish_config_op_enabled __fish_config_op_overrides
+    if type -q ov
+        set -gx PAGER ov
+    else if type -q less
+        set -gx PAGER less
+    end
 end
 
 #   ─────────────────────────── Editor variables ───────────────────────────
@@ -76,7 +94,9 @@ set -gx SCROLLBACK_HISTORY_DIR "$HOME/.terminal_history"
 #   Maximum number of scrollback history files to keep
 set -gx SCROLLBACK_HISTORY_MAX_FILES 100
 # Wire up a clean exit function that won't fire on background subshells
-if status is-interactive
+# Replacing the exit builtin is opinionated (C3 overrides); smart_exit also
+# guards itself so a live toggle takes effect without restarting the shell.
+if status is-interactive; and __fish_config_op_enabled __fish_config_op_overrides
     function exit --description 'Safe interactive exit'
         # If the smart_exit file exists in our function path, invoke it explicitly
         if functions -q smart_exit
@@ -112,7 +132,10 @@ fish_add_path $HOME/.fzf/bin                 # Fuzzy Finder (fzf) core binary an
 # Additionally, directories inside the CWD will still take precedence over CDPATH,
 # so if you have a directory named 'myproject' in the current directory,
 # running 'cd myproject' will take you there instead of $HOME/projects/myproject.
-set -gx CDPATH . $HOME/projects $HOME
+# CDPATH injection is opinionated (C3 overrides)
+if __fish_config_op_enabled __fish_config_op_overrides
+    set -gx CDPATH . $HOME/projects $HOME
+end
 
 #   ──────────────────────────── Bootstrap Fisher ──────────────────────────
 #   Fisher is bootstrapped automatically on first run via conf.d/first_run.fish
@@ -123,7 +146,11 @@ if status is-interactive
     #   ────────────────────────────── Key bindings ────────────────────────────
     #   Helps ensure that key bindings are consistent with the Vi editing mode set below.
     #   This is optional but can improve the user experience for those who prefer Vi-style key bindings.
-    set -g fish_key_bindings fish_vi_key_bindings
+    #   Global Vi mode is opinionated (C3 overrides); without it fish keeps its
+    #   default Emacs-style bindings.
+    if __fish_config_op_enabled __fish_config_op_overrides
+        set -g fish_key_bindings fish_vi_key_bindings
+    end
 
     #   ──────────────────────── Source FZF integration ────────────────────────
     #   Prefer fzf's own fish integration (fzf --fish, available since fzf 0.48)
diff --git a/functions/__fish_config_op_enabled.fish b/functions/__fish_config_op_enabled.fish
new file mode 100644
index 0000000..406888e
--- /dev/null
+++ b/functions/__fish_config_op_enabled.fish
@@ -0,0 +1,46 @@
+# Copyright (C) 2026 Rootiest
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# SYNOPSIS
+#   __fish_config_op_enabled <category_variable>
+#
+# DESCRIPTION
+#   Guard predicate for opinionated components (AGENTS.md Task #3). The master
+#   switch __fish_config_opinionated is always evaluated first via
+#   __fish_variable_check: a falsy master value (0/false/no/off/n) disables
+#   every category at once, regardless of the category variable's own value.
+#   Otherwise the supplied category variable is evaluated the same way.
+#   Unset or empty variables (status 2) and unrecognized values (status 3)
+#   leave the component enabled — opinionated components are active by
+#   default and these variables are pure opt-out knobs.
+#
+# ARGUMENTS
+#   category_variable  Name (without $) of the category opt-out variable:
+#                      __fish_config_op_aliases, __fish_config_op_autoexec,
+#                      __fish_config_op_overrides, or
+#                      __fish_config_op_integrations
+#
+# RETURNS
+#   0  Component enabled (variables truthy, unset, or unrecognized)
+#   1  Component disabled (master or category variable is falsy)
+#
+# EXAMPLE
+#   if __fish_config_op_enabled __fish_config_op_aliases
+#       alias grep='grep --color=auto'
+#   end
+function __fish_config_op_enabled --description 'Check whether an opinionated component category is enabled'
+    # Master switch first: falsy disables all categories unconditionally.
+    __fish_variable_check __fish_config_opinionated
+    if test $status -eq 1
+        return 1
+    end
+
+    # Category variable: only an explicit falsy value disables the category.
+    # Truthy (0), unset/empty (2), and garbage (3) all keep it enabled.
+    __fish_variable_check $argv[1]
+    if test $status -eq 1
+        return 1
+    end
+
+    return 0
+end
-- 
2.52.0


From dc97892a290ecadb0ce4933c300978dc8465de67 Mon Sep 17 00:00:00 2001
From: rootiest <chris@rootiest.com>
Date: Wed, 10 Jun 2026 11:34:56 -0400
Subject: [PATCH 2/4] feat(guards): add in-function opinionated guards and
 CachyOS cleanup

C1 shadows (rm, cat, ls, less, du, bash, top, ping, ssh, rg, mkdir,
help) fall back to the bare command when __fish_config_op_aliases is
falsy; rm falls back to exact 'command rm' with no wrapper. C2 gates
the auto-venv PWD hook. C3 gates smart_exit (composing with Task #4
logging), fish_right_prompt, and all six expand_bang_*/expand_typo_sub
functions atomically with the bang-bang system. C4 integration commands
(spwin, tab, split, hist, logs, upgrade) refuse with a colored stderr
error when disabled. config.fish now also strips the CachyOS distro
config's own bang-bang bindings, history override, and alias opinions
per category, restoring fish stock functions where they exist.
---
 config.fish                                | 25 ++++++++++++++++++++++
 functions/__auto_source_fallback_venv.fish |  5 ++++-
 functions/bash.fish                        |  6 ++++++
 functions/cat.fish                         |  8 ++++++-
 functions/du.fish                          |  6 ++++++
 functions/expand_bang_all.fish             |  3 +++
 functions/expand_bang_caret.fish           |  3 +++
 functions/expand_bang_minus_n.fish         |  3 +++
 functions/expand_bang_search.fish          |  3 +++
 functions/expand_bang_string.fish          |  3 +++
 functions/expand_typo_sub.fish             |  5 ++++-
 functions/fish_right_prompt.fish           |  3 +++
 functions/help.fish                        |  6 ++++++
 functions/hist.fish                        |  8 +++++++
 functions/less.fish                        |  6 ++++++
 functions/logs.fish                        |  8 +++++++
 functions/ls.fish                          |  6 ++++++
 functions/mkdir.fish                       |  6 ++++++
 functions/ping.fish                        |  6 ++++++
 functions/rg.fish                          |  6 ++++++
 functions/rm.fish                          | 10 +++++++++
 functions/smart_exit.fish                  |  7 ++++++
 functions/split.fish                       |  8 +++++++
 functions/spwin.fish                       |  8 +++++++
 functions/ssh.fish                         |  6 ++++++
 functions/tab.fish                         |  8 +++++++
 functions/top.fish                         |  6 ++++++
 functions/upgrade.fish                     |  8 +++++++
 28 files changed, 183 insertions(+), 3 deletions(-)

diff --git a/config.fish b/config.fish
index 07acc3c..89a8051 100644
--- a/config.fish
+++ b/config.fish
@@ -32,6 +32,31 @@ if test -f /usr/share/cachyos-fish-config/cachyos-config.fish
             source "$__fish_config_dir/functions/$_fname.fish"
         end
     end
+
+    # The distro config ships opinionated pieces of its own (it is the origin
+    # of tricks.fish); strip them when the matching category is disabled so
+    # the guards hold on CachyOS systems too.
+    if not __fish_config_op_enabled __fish_config_op_aliases
+        for _fname in grep fgrep egrep dir vdir wget
+            functions -q $_fname; and functions --erase $_fname
+        end
+        # Restore fish's stock versions where they exist (erasing alone would
+        # also block autoloading the stock function).
+        for _fname in history ls
+            functions -q $_fname; and functions --erase $_fname
+            test -f $__fish_data_dir/functions/$_fname.fish
+            and source $__fish_data_dir/functions/$_fname.fish
+        end
+    end
+    if not __fish_config_op_enabled __fish_config_op_overrides
+        for _fname in __history_previous_command __history_previous_command_arguments
+            functions -q $_fname; and functions --erase $_fname
+        end
+        bind --erase ! 2>/dev/null
+        bind --erase '$' 2>/dev/null
+        bind -M insert --erase ! 2>/dev/null
+        bind -M insert --erase '$' 2>/dev/null
+    end
 end
 set --erase _fname
 
diff --git a/functions/__auto_source_fallback_venv.fish b/functions/__auto_source_fallback_venv.fish
index 0cc180c..ab17f05 100644
--- a/functions/__auto_source_fallback_venv.fish
+++ b/functions/__auto_source_fallback_venv.fish
@@ -14,7 +14,10 @@
 #   cd ~/myproject  # activates .venv if present
 function __auto_source_fallback_venv --on-variable PWD
     status --is-command-substitution; and return
-    
+
+    # Opinionated guard (C2): no automatic venv activation when disabled.
+    __fish_config_op_enabled __fish_config_op_autoexec; or return
+
     # 1. Skip if direnv is already managing this directory
     if set -q DIRENV_DIR; or test -e ".envrc"
         return
diff --git a/functions/bash.fish b/functions/bash.fish
index 1ccaa48..5a46f63 100644
--- a/functions/bash.fish
+++ b/functions/bash.fish
@@ -14,6 +14,12 @@
 # EXAMPLE
 #   bash
 function bash --wraps='bash' --description 'bash switches to bash shell'
+    # Opinionated guard (C1): fall back to bare command bash when disabled.
+    if not __fish_config_op_enabled __fish_config_op_aliases
+        command bash $argv
+        return $status
+    end
+
     set SHELL $(which bash) # Set shell to bash
     command bash --rcfile "$XDG_CONFIG_HOME/bash/bashrc" $argv # Run bash
     set SHELL $(which fish) # Reset shell
diff --git a/functions/cat.fish b/functions/cat.fish
index e0d8682..fb993fb 100644
--- a/functions/cat.fish
+++ b/functions/cat.fish
@@ -15,7 +15,13 @@
 # EXAMPLE
 #   cat README.md
 function cat --wraps='bat' --description 'Use bat for files, ls for directories, and raw cat for ANSI logs'
-    # If no arguments are provided, cat usually waits for stdin. 
+    # Opinionated guard (C1): fall back to bare command cat when disabled.
+    if not __fish_config_op_enabled __fish_config_op_aliases
+        command cat $argv
+        return $status
+    end
+
+    # If no arguments are provided, cat usually waits for stdin.
     # We'll maintain that behavior by skipping the directory check if $argv is empty.
     if set -q argv[1]
         if test -d $argv[1]
diff --git a/functions/du.fish b/functions/du.fish
index 4f291e7..903cd3b 100644
--- a/functions/du.fish
+++ b/functions/du.fish
@@ -18,6 +18,12 @@
 # EXAMPLE
 #   du ~/Downloads
 function du --description 'Execute du'
+    # Opinionated guard (C1): fall back to bare command du when disabled.
+    if not __fish_config_op_enabled __fish_config_op_aliases
+        command du $argv
+        return $status
+    end
+
     set cmd ""
     set args
 
diff --git a/functions/expand_bang_all.fish b/functions/expand_bang_all.fish
index 44c6158..bd3940f 100644
--- a/functions/expand_bang_all.fish
+++ b/functions/expand_bang_all.fish
@@ -1,5 +1,8 @@
 # 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
     
diff --git a/functions/expand_bang_caret.fish b/functions/expand_bang_caret.fish
index 99a4539..e1f62a5 100644
--- a/functions/expand_bang_caret.fish
+++ b/functions/expand_bang_caret.fish
@@ -1,5 +1,8 @@
 # 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
diff --git a/functions/expand_bang_minus_n.fish b/functions/expand_bang_minus_n.fish
index b74810a..0a65176 100644
--- a/functions/expand_bang_minus_n.fish
+++ b/functions/expand_bang_minus_n.fish
@@ -1,5 +1,8 @@
 # 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
     
diff --git a/functions/expand_bang_search.fish b/functions/expand_bang_search.fish
index 481f360..de32dd4 100644
--- a/functions/expand_bang_search.fish
+++ b/functions/expand_bang_search.fish
@@ -1,5 +1,8 @@
 # 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)
diff --git a/functions/expand_bang_string.fish b/functions/expand_bang_string.fish
index 6ed3608..a3a497e 100644
--- a/functions/expand_bang_string.fish
+++ b/functions/expand_bang_string.fish
@@ -1,5 +1,8 @@
 # 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"
diff --git a/functions/expand_typo_sub.fish b/functions/expand_typo_sub.fish
index 0ceddf6..d20049a 100644
--- a/functions/expand_typo_sub.fish
+++ b/functions/expand_typo_sub.fish
@@ -1,6 +1,9 @@
 # Execute expand_typo_sub
 function expand_typo_sub --description 'Execute expand_typo_sub'
-    # In newer Fish, the matched token is often passed as $argv[1] 
+    # 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]
diff --git a/functions/fish_right_prompt.fish b/functions/fish_right_prompt.fish
index 7f1642a..df61ec3 100644
--- a/functions/fish_right_prompt.fish
+++ b/functions/fish_right_prompt.fish
@@ -11,6 +11,9 @@
 # EXAMPLE
 #   # Rendered automatically by Fish shell; not called directly.
 function fish_right_prompt --description 'Execute fish_right_prompt'
+    # Opinionated guard (C3): no right prompt when overrides are disabled.
+    __fish_config_op_enabled __fish_config_op_overrides; or return
+
     # 1. Docker Context in Blue
     set -l docker_ctx (docker context show 2>/dev/null)
     if test -n "$docker_ctx"; and test "$docker_ctx" != default
diff --git a/functions/help.fish b/functions/help.fish
index 9cbe5d9..2111ee7 100644
--- a/functions/help.fish
+++ b/functions/help.fish
@@ -66,6 +66,12 @@ end
 
 # --- Wrapper Definition ---
 function help --wraps help --description "Custom wrapper to intercept 'help config'"
+    # Opinionated guard (C1): fall back to the native fish help when disabled.
+    if not __fish_config_op_enabled __fish_config_op_aliases
+        __original_help $argv
+        return $status
+    end
+
     if test "$argv[1]" = config
         # All arguments after 'config' — including flags (-w/--html, -m/--man,
         # -h/--help) and section keywords — are forwarded to config-help.
diff --git a/functions/hist.fish b/functions/hist.fish
index 364723f..39902e4 100644
--- a/functions/hist.fish
+++ b/functions/hist.fish
@@ -11,6 +11,14 @@
 # EXAMPLE
 #   hist
 function hist --description 'Search fish history and put it in the prompt'
+    # Opinionated guard (C4): integrations disabled
+    if not __fish_config_op_enabled __fish_config_op_integrations
+        set -l c_err (set_color red)
+        set -l c_reset (set_color normal)
+        echo "$c_err"'hist: disabled by __fish_config_op_integrations'"$c_reset" >&2
+        return 1
+    end
+
     set -l selected (history | fzf --reverse --height 40% --with-nth 3..)
 
     if test -n "$selected"
diff --git a/functions/less.fish b/functions/less.fish
index 96553e4..aab3caa 100644
--- a/functions/less.fish
+++ b/functions/less.fish
@@ -14,6 +14,12 @@
 # EXAMPLE
 #   less /var/log/syslog
 function less --wraps='ov' --description 'Pager wrapper: $PAGER → ov → less → more → cat'
+    # Opinionated guard (C1): fall back to bare command less when disabled.
+    if not __fish_config_op_enabled __fish_config_op_aliases
+        command less $argv
+        return $status
+    end
+
     if set -q PAGER; and command -q $PAGER
         command $PAGER $argv
     else if command -q ov
diff --git a/functions/logs.fish b/functions/logs.fish
index e45bebe..56800d0 100644
--- a/functions/logs.fish
+++ b/functions/logs.fish
@@ -19,6 +19,14 @@
 # EXAMPLE
 #   logs -c paru
 function logs --description 'Browse terminal log files interactively with fzf'
+    # Opinionated guard (C4): integrations disabled
+    if not __fish_config_op_enabled __fish_config_op_integrations
+        set -l c_err (set_color red)
+        set -l c_reset (set_color normal)
+        echo "$c_err"'logs: disabled by __fish_config_op_integrations'"$c_reset" >&2
+        return 1
+    end
+
     set -l options h/help c/category=
     argparse $options -- $argv
     or return 1
diff --git a/functions/ls.fish b/functions/ls.fish
index d4b1590..89c34bf 100644
--- a/functions/ls.fish
+++ b/functions/ls.fish
@@ -14,6 +14,12 @@
 # EXAMPLE
 #   ls ~/projects
 function ls --description 'List all files'
+    # Opinionated guard (C1): fall back to bare command ls when disabled.
+    if not __fish_config_op_enabled __fish_config_op_aliases
+        command ls $argv
+        return $status
+    end
+
     if which eza >/dev/null 2>&1
         eza -l -a --icons --color=auto --hyperlink $argv
 
diff --git a/functions/mkdir.fish b/functions/mkdir.fish
index 43d6925..6e747f2 100644
--- a/functions/mkdir.fish
+++ b/functions/mkdir.fish
@@ -16,6 +16,12 @@
 # EXAMPLE
 #   mkdir ~/projects/myapp/src
 function mkdir --description 'Execute mkdir'
+    # Opinionated guard (C1): fall back to bare command mkdir when disabled.
+    if not __fish_config_op_enabled __fish_config_op_aliases
+        command mkdir $argv
+        return $status
+    end
+
     if status is-interactive
         # Fall back to command mkdir -p when flags are present (e.g. -m 755)
         for _arg in $argv
diff --git a/functions/ping.fish b/functions/ping.fish
index d07cbcb..7f2e6eb 100644
--- a/functions/ping.fish
+++ b/functions/ping.fish
@@ -17,6 +17,12 @@
 #   ping google.com
 #   ping --legend google.com
 function ping --description 'prettyping with default nolegend'
+    # Opinionated guard (C1): fall back to bare command ping when disabled.
+    if not __fish_config_op_enabled __fish_config_op_aliases
+        command ping $argv
+        return $status
+    end
+
     if command -q prettyping
         # Check if the user specifically asked for the legend
         if contains -- --legend $argv
diff --git a/functions/rg.fish b/functions/rg.fish
index e09b08d..65101de 100644
--- a/functions/rg.fish
+++ b/functions/rg.fish
@@ -15,6 +15,12 @@
 # EXAMPLE
 #   rg "TODO" src/
 function rg --description 'alias rg=rg --hyperlink-format=kitty'
+    # Opinionated guard (C1): fall back to bare command rg when disabled.
+    if not __fish_config_op_enabled __fish_config_op_aliases
+        command rg $argv
+        return $status
+    end
+
     if test "$TERM" = xterm-kitty
         command rg --hyperlink-format=kitty $argv
     else
diff --git a/functions/rm.fish b/functions/rm.fish
index 9b1fb02..1b9cca2 100644
--- a/functions/rm.fish
+++ b/functions/rm.fish
@@ -11,6 +11,10 @@
 #   deletes via rm -rf and triggers fstrim. Plain paths and -r/-R are sent
 #   to trash put; any other flags fall back to system rm.
 #
+#   Opinionated component (C1): when disabled via __fish_config_op_aliases
+#   (or the __fish_config_opinionated master), behaves exactly like bare
+#   command rm — no wrapper, no trash, no trapping.
+#
 # ARGUMENTS
 #   (none)              List current trash contents
 #   -e, --empty [opts]  Empty the trash; opts forwarded to trash empty
@@ -27,6 +31,12 @@
 #   rm -e
 #   rm -S sensitive_key.pem
 function rm --description 'Ultimate rm: trash, list, empty, and secure-erase'
+    # Opinionated guard (C1): fall back to bare command rm when disabled.
+    if not __fish_config_op_enabled __fish_config_op_aliases
+        command rm $argv
+        return $status
+    end
+
     # 1. No arguments: Show the Trash contents (Quick view)
     if not set -q argv[1]
         if type -q trash
diff --git a/functions/smart_exit.fish b/functions/smart_exit.fish
index 3033c0f..eef2fff 100644
--- a/functions/smart_exit.fish
+++ b/functions/smart_exit.fish
@@ -20,6 +20,13 @@
 # EXAMPLE
 #   smart_exit --no-log
 function smart_exit --description 'Capture colorized scrollback before exiting, with pruning and safe overrides'
+    # Opinionated guard (C3): exit plainly when overrides are disabled.
+    # This composes with Task #4's __fish_config_enable_logging, which will
+    # gate only the scrollback capture while leaving the exit wrapper active.
+    if not __fish_config_op_enabled __fish_config_op_overrides
+        builtin exit $argv
+    end
+
     set -l options h/help n/no-log
     argparse $options -- $argv
     or return 1
diff --git a/functions/split.fish b/functions/split.fish
index 5671d74..d87ed3d 100644
--- a/functions/split.fish
+++ b/functions/split.fish
@@ -23,6 +23,14 @@
 #   split
 #   split -v nvim README.md
 function split --description 'Run a command in a new terminal split'
+    # Opinionated guard (C4): integrations disabled
+    if not __fish_config_op_enabled __fish_config_op_integrations
+        set -l c_err (set_color red)
+        set -l c_reset (set_color normal)
+        echo "$c_err"'split: disabled by __fish_config_op_integrations'"$c_reset" >&2
+        return 1
+    end
+
     set -l is_kitty 0
     set -l is_wezterm 0
 
diff --git a/functions/spwin.fish b/functions/spwin.fish
index 985f484..3ab983d 100644
--- a/functions/spwin.fish
+++ b/functions/spwin.fish
@@ -18,6 +18,14 @@
 # EXAMPLE
 #   spwin
 function spwin --wraps='~/.config/kitty/spawn-window.sh' --description 'spawn window in kitty or wezterm'
+    # Opinionated guard (C4): integrations disabled
+    if not __fish_config_op_enabled __fish_config_op_integrations
+        set -l c_err (set_color red)
+        set -l c_reset (set_color normal)
+        echo "$c_err"'spwin: disabled by __fish_config_op_integrations'"$c_reset" >&2
+        return 1
+    end
+
     if test "$TERM" = xterm-kitty
         if test -x ~/.config/kitty/spawn-window.sh
             ~/.config/kitty/spawn-window.sh $argv
diff --git a/functions/ssh.fish b/functions/ssh.fish
index 4313730..394bf00 100644
--- a/functions/ssh.fish
+++ b/functions/ssh.fish
@@ -15,6 +15,12 @@
 # EXAMPLE
 #   ssh user@host
 function ssh --description 'Alias ssh to kitten ssh when using Kitty terminal'
+    # Opinionated guard (C1): fall back to bare command ssh when disabled.
+    if not __fish_config_op_enabled __fish_config_op_aliases
+        command ssh $argv
+        return $status
+    end
+
     if test "$TERM" = xterm-kitty
         kitten ssh $argv
     else
diff --git a/functions/tab.fish b/functions/tab.fish
index 1710c6e..c217aa3 100644
--- a/functions/tab.fish
+++ b/functions/tab.fish
@@ -19,6 +19,14 @@
 # EXAMPLE
 #   tab
 function tab --description 'Spawn a new tab in the current terminal'
+    # Opinionated guard (C4): integrations disabled
+    if not __fish_config_op_enabled __fish_config_op_integrations
+        set -l c_err (set_color red)
+        set -l c_reset (set_color normal)
+        echo "$c_err"'tab: disabled by __fish_config_op_integrations'"$c_reset" >&2
+        return 1
+    end
+
     set -l dir "$cdto"
     if test -z "$dir"
         set dir "$PWD"
diff --git a/functions/top.fish b/functions/top.fish
index c89cc80..c5c471d 100644
--- a/functions/top.fish
+++ b/functions/top.fish
@@ -14,6 +14,12 @@
 # EXAMPLE
 #   top
 function top --wraps='btop' --description 'Use btop as a modern replacement for top'
+    # Opinionated guard (C1): fall back to bare command top when disabled.
+    if not __fish_config_op_enabled __fish_config_op_aliases
+        command top $argv
+        return $status
+    end
+
     # 1. Check if btop is actually installed
     if type -q btop
         # 2. Launch btop with any arguments passed
diff --git a/functions/upgrade.fish b/functions/upgrade.fish
index d3a768c..e5e6ffb 100644
--- a/functions/upgrade.fish
+++ b/functions/upgrade.fish
@@ -15,6 +15,14 @@
 # EXAMPLE
 #   upgrade
 function upgrade --description 'Full system upgrade via paru or yay'
+    # Opinionated guard (C4): integrations disabled
+    if not __fish_config_op_enabled __fish_config_op_integrations
+        set -l c_err (set_color red)
+        set -l c_reset (set_color normal)
+        echo "$c_err"'upgrade: disabled by __fish_config_op_integrations'"$c_reset" >&2
+        return 1
+    end
+
     set -l aur ""
     if type -q paru
         set aur paru
-- 
2.52.0


From 7bd080769edc25b640e18c37f0c4d3ba853451da Mon Sep 17 00:00:00 2001
From: rootiest <chris@rootiest.com>
Date: Wed, 10 Jun 2026 11:38:14 -0400
Subject: [PATCH 3/4] docs(guards): document opinionated component toggles

Adds 'Opinionated Components (Minimal Mode)' to docs/fish-config.md
with index keywords (opinionated, minimal, minimal-mode, opt-out,
toggles) and a Minimal Mode section with toggle table to README.md.
AGENTS.md Task #3 checklist ticked locally (file is git-ignored).
---
 README.md              | 31 ++++++++++++++++++++++++
 docs/fish-config.index |  5 ++++
 docs/fish-config.md    | 55 ++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 91 insertions(+)

diff --git a/README.md b/README.md
index ed38561..82fb34b 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,7 @@ abbreviation system for keyboard-driven workflows.
 - [Documentation](#documentation)
 - [Installation](#installation)
 - [Personalization](#personalization)
+- [Minimal Mode](#minimal-mode)
 - [Attribution](#attribution)
 - [License](#license)
 
@@ -28,6 +29,7 @@ This config layers on top of the CachyOS base Fish configuration and adds:
 - **Kitty terminal** deep integration for splits, tabs, and SSH
 - **AI workflow** helpers for Claude and Antigravity session management
 - **WakaTime** shell activity tracking
+- **Opt-out toggles** for every opinionated component — see [Minimal Mode](#minimal-mode)
 
 ---
 
@@ -162,6 +164,35 @@ end
 
 ---
 
+## Minimal Mode
+
+Everything opinionated in this config — command shadows, startup side-effects, key and environment overrides, and terminal integrations — is active by default but can be switched off with universal variables. Four category toggles and one master switch are available:
+
+| Variable | Disables |
+|---|---|
+| `__fish_config_op_aliases` | Command shadows: `ls`→eza, `cat`→bat, `cd`→zoxide, `rm`→trash, `top`→btop, and friends; `grep`/`cp`/`mv`/`wget` flag injection |
+| `__fish_config_op_autoexec` | Startup side-effects: Fisher bootstrap, theme apply, `paru`/`yay` wrapper generation, auto venv activation, WakaTime hook |
+| `__fish_config_op_overrides` | Vi mode, `exit`→`smart_exit`, `$PAGER`/`$MANPAGER`/`$CDPATH`, bang-bang history expansion, autopair, puffer, Starship prompt, theme colors |
+| `__fish_config_op_integrations` | Kitty/WezTerm window abbreviations, `done` notifications, `spwin`/`tab`/`split`, `hist`, `logs`, `upgrade`, WakaTime |
+| `__fish_config_opinionated` | Master switch — all four categories at once |
+
+Set any of them to a falsy value (`0`, `false`, `no`, `off`, `n`) to disable; erase the variable to re-enable:
+
+```fish
+# Plain shell: disable everything opinionated
+set -U __fish_config_opinionated 0
+
+# Or pick a single category, e.g. keep integrations but drop command shadows
+set -U __fish_config_op_aliases off
+
+# Back to full flavor
+set -Ue __fish_config_opinionated
+```
+
+Command shadows react immediately; bindings, prompt, and abbreviations take effect in new shells. With aliases disabled, `rm` deletes permanently again instead of trashing. See `help config opinionated` for the full component list.
+
+---
+
 ## Attribution
 
 The core of the [Zoxide integration](docs/wiki/2-path-setup.md) in this repository was originally adapted from the [icezyclon/zoxide.fish](https://github.com/icezyclon/zoxide.fish) plugin (MIT Licensed) and has since been heavily customized for performance and Fish 4.x compatibility.
diff --git a/docs/fish-config.index b/docs/fish-config.index
index 06dacd4..b39e85d 100644
--- a/docs/fish-config.index
+++ b/docs/fish-config.index
@@ -162,6 +162,11 @@ local=## Machine-local Configuration
 secrets=## Secrets and API Keys
 overrides=## Overriding Configuration Variables
 universal=## Fish Universal Variables
+opinionated=## Opinionated Components (Minimal Mode)
+minimal=## Opinionated Components (Minimal Mode)
+minimal-mode=## Opinionated Components (Minimal Mode)
+opt-out=## Opinionated Components (Minimal Mode)
+toggles=## Opinionated Components (Minimal Mode)
 
 # ── Section 8: Fisher Plugins ─────────────────────────────────
 plugins=# 8. FISHER PLUGINS
diff --git a/docs/fish-config.md b/docs/fish-config.md
index 2ca8a6a..5701818 100644
--- a/docs/fish-config.md
+++ b/docs/fish-config.md
@@ -1375,6 +1375,61 @@ Some settings (fzf colors, theme) are stored in fish_variables via
 `set -U`. These are machine-local and git-ignored. Do not commit
 fish_variables.
 
+## Opinionated Components (Minimal Mode)
+
+Every opinionated piece of this config is active by default but can be
+switched off through four category opt-out variables, each evaluated via
+__fish_variable_check. Set a variable to any falsy value (0, false, no,
+off, n) to disable its category; erase it or set a truthy value (1, true,
+yes, on, y) to re-enable. Unset means enabled.
+
+    Variable                        Disables
+    ------------------------------  ------------------------------------
+    __fish_config_op_aliases        Command shadows and flag injection:
+                                    ls->eza, cat->bat, cd->zoxide,
+                                    rm->trash, less->ov, top->btop,
+                                    ping->prettyping, ssh->kitten,
+                                    du->duf/dust, mkdir/bash wrappers,
+                                    history timestamps, grep/cp/mv/wget
+                                    flag injection, help intercept
+    __fish_config_op_autoexec       Startup side-effects: Fisher
+                                    bootstrap, theme apply, paru/yay
+                                    wrapper generation, auto venv
+                                    activation, WakaTime hook
+    __fish_config_op_overrides      Key and env overrides: Vi mode,
+                                    exit->smart_exit, PAGER/MANPAGER,
+                                    CDPATH, bang-bang system, autopair,
+                                    puffer, starship prompt, theme
+                                    colors, FZF_DEFAULT_OPTS, right
+                                    prompt
+    __fish_config_op_integrations   Terminal/tool coupling: Kitty/
+                                    WezTerm window abbreviations, done
+                                    notifications, spwin/tab/split,
+                                    hist, logs, upgrade, WakaTime
+
+Examples:
+
+    # Disable command shadows only (rm becomes plain rm again):
+    set -U __fish_config_op_aliases off
+
+    # Full minimal mode — disable all four categories at once:
+    set -U __fish_config_opinionated 0
+
+    # Re-enable everything:
+    set -Ue __fish_config_opinionated
+
+Notes:
+
+  - Command shadows (rm, cat, ls, ...) react immediately; conf.d-level
+    components (bindings, prompt, abbreviations, hooks) take effect in
+    new shells.
+  - With aliases disabled, rm falls back to bare `command rm` — files
+    are deleted permanently, not trashed.
+  - Disabled integration commands (spwin, tab, split, hist, logs,
+    upgrade) print an error naming the variable that disabled them.
+  - On CachyOS, the distro fish config's own aliases, history override,
+    and bang-bang bindings are stripped per category as well.
+
 ## Prompt and Theme
 
 ### Starship
-- 
2.52.0


From e30fc7a15c55f8d1f08b04fa6423698b7014ad4f Mon Sep 17 00:00:00 2001
From: rootiest <chris@rootiest.com>
Date: Wed, 10 Jun 2026 11:41:04 -0400
Subject: [PATCH 4/4] docs(config-vars): cross-reference minimal mode from
 Section 1 Other

---
 docs/fish-config.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/fish-config.md b/docs/fish-config.md
index 5701818..fa53b22 100644
--- a/docs/fish-config.md
+++ b/docs/fish-config.md
@@ -156,6 +156,10 @@ automatically on exit. Use `logs` to browse them interactively.
     CLAUDE_CODE_NO_FLICKER  1    — suppress terminal flicker in Claude Code
     CDPATH               . ~/projects ~
 
+Opinionated defaults (CDPATH, PAGER/MANPAGER, Vi mode, command shadows,
+terminal integrations) can be switched off per category with universal
+variables — see Section 7, "Opinionated Components (Minimal Mode)".
+
 ## Pager Hierarchy
 
 $PAGER is set to ov when available, falling back to less. The less wrapper
-- 
2.52.0