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

@@ -76,6 +76,8 @@ abbr -a ag antigravity
 abbr -a ag. antigravity .
 # Quit
 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
         abbr -a :q kitty @ close-window # Kitty (Closes the active split/pane)
         abbr -a :Q kitty @ close-tab # Kitty (Closes the whole tab)
@@ -84,6 +86,7 @@ if test "$TERM_PROGRAM" = WezTerm
         abbr -a :q wezterm cli kill-pane # WezTerm
         abbr -a :Q wezterm cli kill-pane # WezTerm
     end
+end
 
 ######### Alternates ##########
 ### ls alternates
@@ -103,6 +106,9 @@ abbr -a lsT lstree
 # Speedtest using fast.com
 abbr -a speedtest-fast fast-cli
 
+# 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
@@ -282,6 +288,7 @@ end
     if test "$TERM" = xterm-kitty
         abbr -a :sw spwin
     end
+end
 
 ### Docker ###
 abbr -a dcl 'docker context use default # Local Host'
@@ -307,9 +314,13 @@ abbr -a sscs 'sudo systemctl start'
 abbr -a sscr 'sudo systemctl restart'
 
 ### 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
     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

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 "()" "[]" "{}" '""' "''"

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

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..."

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:

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

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

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

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

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,6 +41,9 @@ set -gx __done_notification_urgency_level low
 
 ## Functions
 # Functions needed for !! and !$ https://github.com/oh-my-fish/plugin-bang-bang
+# 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 "!"
@@ -68,11 +72,16 @@ else
         bind ! __history_previous_command
         bind '$' __history_previous_command_arguments
     end
+end
 
 # Fish command history override to show timestamps
+# 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
 function backup --argument filename
@@ -97,6 +106,8 @@ alias ....='cd ../../..'
 alias .....='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
     alias dir='dir --color=auto'
     alias vdir='vdir --color=auto'
@@ -108,10 +119,13 @@ alias egrep='egrep --color=auto'
     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

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

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

conf.d/zoxide.fish

@@ -63,7 +63,11 @@ if status is-interactive
 
         # -------------
 
+        # 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 

config.fish

@@ -5,9 +5,23 @@
 #          │                    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
+    # 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"
@@ -18,6 +32,7 @@ if test -f /usr/share/cachyos-fish-config/cachyos-config.fish
             source "$__fish_config_dir/functions/$_fname.fish"
         end
     end
+end
 set --erase _fname
 
 #   ───────────────────────────── XDG variables ────────────────────────────
@@ -47,11 +62,14 @@ set -gx CODEIUM_HOME "$XDG_CONFIG_HOME/codeium"
 set -gx WORDLIST "$XDG_CONFIG_HOME/hunspell_en_US"
 
 #   ─────────────────────────── Pager variables ────────────────────────────
+# 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 ───────────────────────────
 #   Set Editor variables with fallback to vi if nvim isn't available. This ensures that
@@ -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.
+# 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.
+    #   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)

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