feat: gate XDG and PATH behind overrides toggle

Wrapped the XDG variables and PATH setup in config.fish with the C3 overrides toggle so users can fully opt out. Updated the documentation (07-customization.md, 02-path-setup.md, README.md) to reflect this. Also added a Home link to the 404 page and removed a leftover test_sidebar.js file.
2026-07-27 01:33:21 -04:00
parent 3155449ef6
commit e180e8d452
6 changed files with 48 additions and 33 deletions
@@ -279,7 +279,7 @@ If you'd rather set them by hand, each category is controlled by a universal var
 |---|---|
 | `__fish_config_op_aliases` | Command shadows: `ls`→eza, `cat`→bat, `cd`→zoxide, `rm`→trash, `top`→btop, `edit`→multi-editor launcher, 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, auto-pull background fast-forward |
-| `__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_overrides` | Vi mode, `exit`→`smart_exit`, `$PAGER`/`$MANPAGER`/`$CDPATH`/`XDG`/`PATH`, 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_op_logging` | Scrollback capture on exit, tmux `pipe-pane` pane logging, zellij `dump-screen` capture on exit, `paru`/`yay` AUR log wrappers, Kitty watcher capture (sentinel-file coordinated) |
 | `__fish_config_op_greeting` | Per-session `fish_greeting` (suppresses distro greetings such as CachyOS fastfetch by overriding with an empty function); first-run welcome banner |
@@ -64,29 +64,32 @@ set --erase _fname

 #   ───────────────────────────── XDG variables ────────────────────────────
 # XDG Base Directory variables (standard practice)
-set -gx XDG_CONFIG_HOME $HOME/.config # Sets default config dir to ~/.config
-set -gx XDG_CACHE_HOME $HOME/.cache # Sets default cache dir to ~/.cache
-set -gx XDG_DATA_HOME $HOME/.local/share # Sets default data dir to ~/.local/share
-set -gx XDG_STATE_HOME $HOME/.local/state # Sets default state dir to ~/.local/state
+# Setting XDG variables globally is opinionated (C3 overrides)
+if __fish_config_op_enabled __fish_config_op_overrides
+    set -gx XDG_CONFIG_HOME $HOME/.config # Sets default config dir to ~/.config
+    set -gx XDG_CACHE_HOME $HOME/.cache # Sets default cache dir to ~/.cache
+    set -gx XDG_DATA_HOME $HOME/.local/share # Sets default data dir to ~/.local/share
+    set -gx XDG_STATE_HOME $HOME/.local/state # Sets default state dir to ~/.local/state

-# Attempt to keep various config/cache files out of the home directory root
-set -gx RANDFILE "$XDG_STATE_HOME/rnd"
-set -gx WGETRC "$XDG_CONFIG_HOME/wget/wgetrc"
-set -gx WGET_HSTS_FILE "$XDG_CACHE_HOME/wget-hsts"
-set -gx NPM_CONFIG_PREFIX "$XDG_DATA_HOME/npm-global"
-set -gx NPM_CONFIG_USERCONFIG "$XDG_CONFIG_HOME/npm/npmrc"
-set -gx ANDROID_USER_HOME "$XDG_DATA_HOME/android"
-set -gx CARGO_HOME "$XDG_DATA_HOME/cargo"
-set -gx RUSTUP_HOME "$XDG_DATA_HOME/rustup"
-set -gx GOPATH "$XDG_DATA_HOME/go"
-set -gx BUN_INSTALL "$XDG_DATA_HOME/bun"
-set -gx GNUPGHOME "$XDG_CONFIG_HOME/gnupg"
-set -gx WAKATIME_HOME "$XDG_CONFIG_HOME/wakatime"
-set -gx HISTFILE "$XDG_STATE_HOME/bash_history"
-set -gx EXINIT "set viminfofile=$XDG_STATE_HOME/vim/viminfo | source $MYVIMRC"
-set -gx NVIDIA_SETTINGS_RW_CONFIG_FILE "$XDG_CONFIG_HOME/nvidia/settings"
-set -gx CODEIUM_HOME "$XDG_CONFIG_HOME/codeium"
-set -gx WORDLIST "$XDG_CONFIG_HOME/hunspell_en_US"
+    # Attempt to keep various config/cache files out of the home directory root
+    set -gx RANDFILE "$XDG_STATE_HOME/rnd"
+    set -gx WGETRC "$XDG_CONFIG_HOME/wget/wgetrc"
+    set -gx WGET_HSTS_FILE "$XDG_CACHE_HOME/wget-hsts"
+    set -gx NPM_CONFIG_PREFIX "$XDG_DATA_HOME/npm-global"
+    set -gx NPM_CONFIG_USERCONFIG "$XDG_CONFIG_HOME/npm/npmrc"
+    set -gx ANDROID_USER_HOME "$XDG_DATA_HOME/android"
+    set -gx CARGO_HOME "$XDG_DATA_HOME/cargo"
+    set -gx RUSTUP_HOME "$XDG_DATA_HOME/rustup"
+    set -gx GOPATH "$XDG_DATA_HOME/go"
+    set -gx BUN_INSTALL "$XDG_DATA_HOME/bun"
+    set -gx GNUPGHOME "$XDG_CONFIG_HOME/gnupg"
+    set -gx WAKATIME_HOME "$XDG_CONFIG_HOME/wakatime"
+    set -gx HISTFILE "$XDG_STATE_HOME/bash_history"
+    set -gx EXINIT "set viminfofile=$XDG_STATE_HOME/vim/viminfo | source $MYVIMRC"
+    set -gx NVIDIA_SETTINGS_RW_CONFIG_FILE "$XDG_CONFIG_HOME/nvidia/settings"
+    set -gx CODEIUM_HOME "$XDG_CONFIG_HOME/codeium"
+    set -gx WORDLIST "$XDG_CONFIG_HOME/hunspell_en_US"
+end

 #   ─────────────────────────── Pager variables ────────────────────────────
 # Overriding $PAGER is opinionated (C3 overrides)
@@ -147,16 +150,19 @@ end
 #   Adds common user bin directories to the PATH. The -mg --move option for cargo ensures that
 #   the cargo bin directory is moved to the end of the PATH, which can help avoid conflicts
 #   with system-installed Rust tools while still allowing user-installed cargo binaries to be found.
-fish_add_path $HOME/.local/bin # Standard user-local executables (XDG spec)
-fish_add_path $HOME/.local/share/../bin # Alternative/legacy path for local user binaries
-fish_add_path $HOME/Applications # User-installed applications and standalone apps
-fish_add_path $HOME/scripts # Custom personal shell scripts and automation
-fish_add_path -mga $CARGO_HOME/bin # Rust binaries and tools installed via Cargo
-fish_add_path $BUN_INSTALL/bin # Bun runtime executables and globally installed packages
-fish_add_path $XDG_DATA_HOME/npm-global/bin # Global Node.js/npm packages (XDG compliant location)
-fish_add_path $HOME/.lmstudio/bin # LM Studio CLI tools for local LLM management
-fish_add_path $HOME/.resend/bin # Resend email service CLI tools
-fish_add_path $HOME/.fzf/bin # Fuzzy Finder (fzf) core binary and helper scripts
+#   PATH setup is opinionated (C3 overrides)
+if __fish_config_op_enabled __fish_config_op_overrides
+    fish_add_path $HOME/.local/bin # Standard user-local executables (XDG spec)
+    fish_add_path $HOME/.local/share/../bin # Alternative/legacy path for local user binaries
+    fish_add_path $HOME/Applications # User-installed applications and standalone apps
+    fish_add_path $HOME/scripts # Custom personal shell scripts and automation
+    fish_add_path -mga $CARGO_HOME/bin # Rust binaries and tools installed via Cargo
+    fish_add_path $BUN_INSTALL/bin # Bun runtime executables and globally installed packages
+    fish_add_path $XDG_DATA_HOME/npm-global/bin # Global Node.js/npm packages (XDG compliant location)
+    fish_add_path $HOME/.lmstudio/bin # LM Studio CLI tools for local LLM management
+    fish_add_path $HOME/.resend/bin # Resend email service CLI tools
+    fish_add_path $HOME/.fzf/bin # Fuzzy Finder (fzf) core binary and helper scripts
+end

 #   ───────────────────────── CDPATH projects dir ──────────────────────────
 # Allows cd-ing to directories within $HOME/projects or $HOME without needing to specify the full path.
@@ -310,6 +310,8 @@ shadowing system-installed Rust tools.

 NOTE: While these directories are merged with your system's existing `$PATH` values, any executables in the prepended directories above will override (shadow) system binaries of the same name.

+TIP: This standard PATH setup is gated behind the opinionated component overrides toggle. If you prefer to manage your PATH completely manually, you can disable it by setting `__fish_config_op_overrides` to `0` (or toggle it off in the `config-settings` menu).
+
 ---

 # 3. KEY BINDINGS
@@ -2720,6 +2722,8 @@ all of them.
    Override                  What it replaces or sets
    ───────────────────────────────────────────────────────────────────────────
    Vi mode                   fish_vi_key_bindings replaces default Emacs mode
+    XDG variables             Sets global XDG Base Directory variables
+    PATH setup                Prepends custom bin directories to the PATH
    exit → smart_exit         exit wrapper that captures scrollback before closing
    PAGER=ov                  ov used by git, man, and all $PAGER-aware tools
    MANPAGER=bat pipeline     man pages rendered with syntax highlighting
@@ -26,4 +26,6 @@ shadowing system-installed Rust tools.

 NOTE: While these directories are merged with your system's existing `$PATH` values, any executables in the prepended directories above will override (shadow) system binaries of the same name.

+TIP: This standard PATH setup is gated behind the opinionated component overrides toggle. If you prefer to manage your PATH completely manually, you can disable it by setting `__fish_config_op_overrides` to `0` (or toggle it off in the `config-settings` menu).
+
 ---
@@ -219,6 +219,8 @@ all of them.
    Override                  What it replaces or sets
    ───────────────────────────────────────────────────────────────────────────
    Vi mode                   fish_vi_key_bindings replaces default Emacs mode
+    XDG variables             Sets global XDG Base Directory variables
+    PATH setup                Prepends custom bin directories to the PATH
    exit → smart_exit         exit wrapper that captures scrollback before closing
    PAGER=ov                  ov used by git, man, and all $PAGER-aware tools
    MANPAGER=bat pipeline     man pages rendered with syntax highlighting
@@ -9,6 +9,7 @@ hero:
 ---

 <CardGrid>
+  <LinkCard title="Home" description="Return to the main manual page" href="/" />
  <LinkCard title="Installation" description="Set up the configuration" href="/09-installation/" />
  <LinkCard title="Troubleshooting" description="Fix common issues" href="/11-troubleshooting/" />
  <LinkCard title="Function Reference" description="Browse all functions" href="/05-functions/" />