chore(docs): regenerate man page, HTML docs, and wiki

docs/fish-config.1

@@ -792,6 +792,20 @@ rm -e                 # empty trash
 rm -S sensitive.pem   # permanent delete
 \f[R]
 .fi
+.SS rg
+.IP
+.nf
+\f[C]
+Synopsis:  rg [args...]
+In Kitty, wraps ripgrep with --hyperlink-format=kitty so search
+results are clickable file links in the terminal. Falls back to
+system rg in any other terminal. All other arguments pass through
+unchanged.
+
+rg \[dq]fish_greeting\[dq] \[ti]/.config/fish/
+rg -l \[dq]TODO\[dq] \[ti]/projects/myapp
+\f[R]
+.fi
 .SS scrub
 .IP
 .nf
@@ -1863,6 +1877,205 @@ print an error naming the variable that disabled them.
 .IP \[bu] 2
 On CachyOS, the distro fish config\[cq]s own aliases, history override,
 and bang-bang bindings are stripped per category as well.
+.SS Component Reference
+.PP
+The following tables detail every component in each category.
+Use this reference to understand exactly which behaviors change when you
+toggle a category variable.
+.SS C1 \[em] Command Shadows
+.PP
+Disabling __fish_config_op_aliases restores standard system behavior for
+all of these commands.
+.IP
+.nf
+\f[C]
+Command / Alias    Active behavior                       Disabled fallback
+───────────────────────────────────────────────────────────────────────────
+ls                 eza -l -a --icons --hyperlink          system ls
+cat                bat syntax-highlighted; dirs → ls      /usr/bin/cat
+cd                 zoxide frecency-based navigation        fish builtin cd
+rm                 moves files to trash (recoverable)     command rm (permanent)
+less               $PAGER → ov → less → more → cat       system less
+du                 duf (disk overview) or dust (dir tree) system du
+top                btop resource monitor                  system top
+ping               prettyping --nolegend animation        system ping
+ssh                kitten ssh in Kitty terminal           system ssh
+rg                 rg --hyperlink-format=kitty            system rg
+mkdir              verbose path-tree display on creation  mkdir -p silently
+bash               XDG bashrc + $SHELL reset on exit      system bash
+history            timestamps prepended to every entry    fish builtin history
+cp / mv            forced -i confirmation prompt          cp / mv unmodified
+wget               forced --continue (resume downloads)   system wget
+grep/fgrep/egrep   forced --color=auto                    system grep variants
+dir / vdir         forced --color=auto                    system dir / vdir
+help config        intercepts \[dq]help config\[dq] → config-help fish builtin help
+\f[R]
+.fi
+.PP
+When C1 is disabled, \f[V]rm\f[R] uses bare \f[V]command rm\f[R] with no
+wrapper \[em] files are permanently deleted, not trashed.
+There is no intermediate safety net.
+.SS C2 \[em] Startup Side-Effects
+.PP
+These run automatically without any user action.
+Disabling __fish_config_op_autoexec prevents all of them.
+.IP
+.nf
+\f[C]
+Component                  Trigger              What it does
+───────────────────────────────────────────────────────────────────────────
+Fisher bootstrap           First shell only     Downloads and installs fisher
+Fisher update              After bootstrap      Installs all fish_plugins entries
+Catppuccin Mocha theme     First shell only     Applies theme via fish_config
+paru wrapper               Every startup        Writes \[ti]/.local/bin/paru wrapper
+yay wrapper                Every startup        Writes \[ti]/.local/bin/yay wrapper
+Python venv activation     On every cd          Sources .venv/bin/activate.fish
+WakaTime command hook      On every command     Reports to WakaTime API
+\f[R]
+.fi
+.PP
+When C2 is disabled: no Fisher install, no theme application, no
+paru/yay wrapper generation, no automatic venv activation, and no
+WakaTime reporting.
+The first-run completion marker (__fish_config_first_run_complete) is
+still set so the init does not re-run on subsequent shells.
+.PP
+Python venv activation fires on every directory change.
+If a directory uses direnv (.envrc present), direnv takes priority and
+auto-venv is skipped for that directory.
+.SS C3 \[em] Key and Environment Overrides
+.PP
+These change fundamental shell behavior: how keys work, which pager
+opens, and what the prompt looks like.
+Disabling __fish_config_op_overrides removes all of them.
+.IP
+.nf
+\f[C]
+Override                  What it replaces or sets
+───────────────────────────────────────────────────────────────────────────
+Vi mode                   fish_vi_key_bindings replaces default Emacs mode
+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
+CDPATH=. \[ti]/projects \[ti]     bare dir names resolve against \[ti]/projects and \[ti]
+Bang-bang system          ! and $ keys expand history; !\[ha], !*, !-N, !?str?,
+                          \[ha]old\[ha]new abbreviations; six expand_bang_* helpers
+Autopair                  ( [ { \[dq] \[aq] auto-close to (), [], {}, \[dq]\[dq], \[aq]\[aq]
+Puffer key intercepts     . ! $ * keys intercepted for smart expansion
+Starship prompt           fish_prompt replaced by Starship + OSC 133 markers
+Catppuccin colors         30+ fish_color_* variables set to Mocha palette
+FZF_DEFAULT_OPTS          FZF themed to Catppuccin Mocha colors
+Right prompt              fish_right_prompt: Docker context + timestamp
+\f[R]
+.fi
+.PP
+The bang-bang system spans key_bindings.fish, abbr.fish, puffer.fish,
+and six expand_bang_*.fish functions.
+All are gated together \[em] disabling C3 removes the entire
+bang-expansion system at once.
+.PP
+When C3 is disabled, \f[V]exit\f[R] falls back to \f[V]builtin exit\f[R]
+with no scrollback capture, no Kitty IPC, and no file I/O on exit.
+The scrollback capture block is independently controlled by C5 (see
+below).
+.SS C4 \[em] Terminal and Tool Integration
+.PP
+These features couple the shell to specific external tools.
+Disabling __fish_config_op_integrations disables all of them.
+.IP
+.nf
+\f[C]
+Component                  Requires
+───────────────────────────────────────────────────────────────────────────
+\[ti]60 Kitty/WezTerm abbrs    Active Kitty or WezTerm session
+  (:w, :wv, :wh, :t, etc.)
+Done desktop notifications Graphical desktop with a notification daemon
+spwin                      Kitty or WezTerm
+tab                        Kitty, WezTerm, or Konsole
+split                      Kitty or WezTerm
+hist                       fzf + wl-copy (Wayland clipboard)
+logs                       fzf + ov; reads from \[ti]/.terminal_history/
+upgrade                    paru or yay (Arch Linux only)
+WakaTime hook              wakatime CLI and a configured API key
+\f[R]
+.fi
+.PP
+Disabled integration commands (spwin, tab, split, hist, logs, upgrade)
+print a colored error to stderr naming the variable that disabled them
+rather than silently failing.
+.SS C5 \[em] Logging and Capture
+.PP
+Three components capture shell output to disk.
+Disabling __fish_config_op_logging skips all capture and removes the
+logging wrappers.
+.IP
+.nf
+\f[C]
+Component               What it captures
+───────────────────────────────────────────────────────────────────────────
+Scrollback capture      Terminal session output saved to:
+                        \[ti]/.terminal_history/scrollback_YYYY-MM-DD_HH-MM-SS.log
+paru wrapper            All paru/AUR output teed to:
+                        \[ti]/.terminal_history/paru_YYYY-MM-DD_HH-MM-SS.log
+yay wrapper             All yay/AUR output teed to:
+                        \[ti]/.terminal_history/yay_YYYY-MM-DD_HH-MM-SS.log
+Kitty watcher           watcher.py captures scrollback when Kitty closes
+\f[R]
+.fi
+.PP
+Logging coordination via sentinel file
+.PP
+C5 uses a sentinel file to synchronize state between the shell and
+out-of-process components (the Kitty watcher and all running shells):
+.IP
+.nf
+\f[C]
+\[ti]/.config/fish/.logging_disabled
+\f[R]
+.fi
+.PP
+Disabling __fish_config_op_logging: 1.
+Creates the sentinel immediately in every open shell.
+2.
+Removes \[ti]/.local/bin/paru and \[ti]/.local/bin/yay logging wrappers;
+bare /usr/bin/paru and /usr/bin/yay are used instead.
+3.
+Kitty\[cq]s watcher.py reads the sentinel on each save attempt and skips
+capture \[em] no Kitty restart required.
+4.
+smart_exit stops saving scrollback logs.
+.PP
+Re-enabling __fish_config_op_logging: 1.
+Removes the sentinel in every open shell.
+2.
+Regenerates paru/yay logging wrappers in \[ti]/.local/bin/.
+3.
+Kitty watcher resumes capture on the next session exit.
+.PP
+Changes propagate to all running shells through an event handler that
+fires whenever __fish_config_op_logging changes \[em] no shell restart
+needed.
+.PP
+Note: C3 and C5 compose independently.
+C3 controls whether the smart_exit wrapper is active at all; C5 controls
+only the scrollback-capture block inside it.
+With C3 disabled, exit is plain builtin exit regardless of C5.
+.SS C6 \[em] Greeting and First-Run UI
+.IP
+.nf
+\f[C]
+Component                  What it shows
+───────────────────────────────────────────────────────────────────────────
+First-run welcome banner   One-time message on first interactive session
+fish_greeting override     Empty function defined late in config.fish to
+                           suppress distro greetings (e.g. CachyOS sets
+                           fish_greeting to fastfetch by default)
+\f[R]
+.fi
+.PP
+When C6 is disabled, no greeting is printed by this config.
+Any greeting set by the distro or other configs runs normally \[em] this
+config simply does not override it.
 .SS Prompt and Theme
 .SS Starship
 .PP

docs/html/11-7-customization.html

@@ -587,6 +587,157 @@ upgrade) print an error naming the variable that disabled them.</li>
 <li>On CachyOS, the distro fish config's own aliases, history override,
 and bang-bang bindings are stripped per category as well.</li>
 </ul>
+<h3 data-number="11.5.1" id="component-reference">Component
+Reference</h3>
+<p>The following tables detail every component in each category. Use
+this reference to understand exactly which behaviors change when you
+toggle a category variable.</p>
+<h4 data-number="11.5.1.1" id="c1--command-shadows">C1 — Command
+Shadows</h4>
+<p>Disabling __fish_config_op_aliases restores standard system behavior
+for all of these commands.</p>
+<pre><code>Command / Alias    Active behavior                       Disabled fallback
+───────────────────────────────────────────────────────────────────────────
+ls                 eza -l -a --icons --hyperlink          system ls
+cat                bat syntax-highlighted; dirs → ls      /usr/bin/cat
+cd                 zoxide frecency-based navigation        fish builtin cd
+rm                 moves files to trash (recoverable)     command rm (permanent)
+less               $PAGER → ov → less → more → cat       system less
+du                 duf (disk overview) or dust (dir tree) system du
+top                btop resource monitor                  system top
+ping               prettyping --nolegend animation        system ping
+ssh                kitten ssh in Kitty terminal           system ssh
+rg                 rg --hyperlink-format=kitty            system rg
+mkdir              verbose path-tree display on creation  mkdir -p silently
+bash               XDG bashrc + $SHELL reset on exit      system bash
+history            timestamps prepended to every entry    fish builtin history
+cp / mv            forced -i confirmation prompt          cp / mv unmodified
+wget               forced --continue (resume downloads)   system wget
+grep/fgrep/egrep   forced --color=auto                    system grep variants
+dir / vdir         forced --color=auto                    system dir / vdir
+help config        intercepts &quot;help config&quot; → config-help fish builtin help</code></pre>
+<p>When C1 is disabled, <code>rm</code> uses bare
+<code>command rm</code> with no wrapper — files are permanently deleted,
+not trashed. There is no intermediate safety net.</p>
+<h4 data-number="11.5.1.2" id="c2--startup-side-effects">C2 — Startup
+Side-Effects</h4>
+<p>These run automatically without any user action. Disabling
+__fish_config_op_autoexec prevents all of them.</p>
+<pre><code>Component                  Trigger              What it does
+───────────────────────────────────────────────────────────────────────────
+Fisher bootstrap           First shell only     Downloads and installs fisher
+Fisher update              After bootstrap      Installs all fish_plugins entries
+Catppuccin Mocha theme     First shell only     Applies theme via fish_config
+paru wrapper               Every startup        Writes ~/.local/bin/paru wrapper
+yay wrapper                Every startup        Writes ~/.local/bin/yay wrapper
+Python venv activation     On every cd          Sources .venv/bin/activate.fish
+WakaTime command hook      On every command     Reports to WakaTime API</code></pre>
+<p>When C2 is disabled: no Fisher install, no theme application, no
+paru/yay wrapper generation, no automatic venv activation, and no
+WakaTime reporting. The first-run completion marker
+(__fish_config_first_run_complete) is still set so the init does not
+re-run on subsequent shells.</p>
+<p>Python venv activation fires on every directory change. If a
+directory uses direnv (.envrc present), direnv takes priority and
+auto-venv is skipped for that directory.</p>
+<h4 data-number="11.5.1.3" id="c3--key-and-environment-overrides">C3 —
+Key and Environment Overrides</h4>
+<p>These change fundamental shell behavior: how keys work, which pager
+opens, and what the prompt looks like. Disabling
+__fish_config_op_overrides removes all of them.</p>
+<pre><code>Override                  What it replaces or sets
+───────────────────────────────────────────────────────────────────────────
+Vi mode                   fish_vi_key_bindings replaces default Emacs mode
+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
+CDPATH=. ~/projects ~     bare dir names resolve against ~/projects and ~
+Bang-bang system          ! and $ keys expand history; !^, !*, !-N, !?str?,
+                          ^old^new abbreviations; six expand_bang_* helpers
+Autopair                  ( [ { &quot; &#39; auto-close to (), [], {}, &quot;&quot;, &#39;&#39;
+Puffer key intercepts     . ! $ * keys intercepted for smart expansion
+Starship prompt           fish_prompt replaced by Starship + OSC 133 markers
+Catppuccin colors         30+ fish_color_* variables set to Mocha palette
+FZF_DEFAULT_OPTS          FZF themed to Catppuccin Mocha colors
+Right prompt              fish_right_prompt: Docker context + timestamp</code></pre>
+<p>The bang-bang system spans key_bindings.fish, abbr.fish, puffer.fish,
+and six expand_bang_*.fish functions. All are gated together — disabling
+C3 removes the entire bang-expansion system at once.</p>
+<p>When C3 is disabled, <code>exit</code> falls back to
+<code>builtin exit</code> with no scrollback capture, no Kitty IPC, and
+no file I/O on exit. The scrollback capture block is independently
+controlled by C5 (see below).</p>
+<h4 data-number="11.5.1.4" id="c4--terminal-and-tool-integration">C4 —
+Terminal and Tool Integration</h4>
+<p>These features couple the shell to specific external tools. Disabling
+__fish_config_op_integrations disables all of them.</p>
+<pre><code>Component                  Requires
+───────────────────────────────────────────────────────────────────────────
+~60 Kitty/WezTerm abbrs    Active Kitty or WezTerm session
+  (:w, :wv, :wh, :t, etc.)
+Done desktop notifications Graphical desktop with a notification daemon
+spwin                      Kitty or WezTerm
+tab                        Kitty, WezTerm, or Konsole
+split                      Kitty or WezTerm
+hist                       fzf + wl-copy (Wayland clipboard)
+logs                       fzf + ov; reads from ~/.terminal_history/
+upgrade                    paru or yay (Arch Linux only)
+WakaTime hook              wakatime CLI and a configured API key</code></pre>
+<p>Disabled integration commands (spwin, tab, split, hist, logs,
+upgrade) print a colored error to stderr naming the variable that
+disabled them rather than silently failing.</p>
+<h4 data-number="11.5.1.5" id="c5--logging-and-capture">C5 — Logging and
+Capture</h4>
+<p>Three components capture shell output to disk. Disabling
+__fish_config_op_logging skips all capture and removes the logging
+wrappers.</p>
+<pre><code>Component               What it captures
+───────────────────────────────────────────────────────────────────────────
+Scrollback capture      Terminal session output saved to:
+                        ~/.terminal_history/scrollback_YYYY-MM-DD_HH-MM-SS.log
+paru wrapper            All paru/AUR output teed to:
+                        ~/.terminal_history/paru_YYYY-MM-DD_HH-MM-SS.log
+yay wrapper             All yay/AUR output teed to:
+                        ~/.terminal_history/yay_YYYY-MM-DD_HH-MM-SS.log
+Kitty watcher           watcher.py captures scrollback when Kitty closes</code></pre>
+<p>Logging coordination via sentinel file</p>
+<p>C5 uses a sentinel file to synchronize state between the shell and
+out-of-process components (the Kitty watcher and all running
+shells):</p>
+<pre><code>~/.config/fish/.logging_disabled</code></pre>
+<p>Disabling __fish_config_op_logging:</p>
+<ol type="1">
+<li>Creates the sentinel immediately in every open shell.</li>
+<li>Removes ~/.local/bin/paru and ~/.local/bin/yay logging wrappers;
+bare /usr/bin/paru and /usr/bin/yay are used instead.</li>
+<li>Kitty's watcher.py reads the sentinel on each save attempt and skips
+capture — no Kitty restart required.</li>
+<li>smart_exit stops saving scrollback logs.</li>
+</ol>
+<p>Re-enabling __fish_config_op_logging:</p>
+<ol type="1">
+<li>Removes the sentinel in every open shell.</li>
+<li>Regenerates paru/yay logging wrappers in ~/.local/bin/.</li>
+<li>Kitty watcher resumes capture on the next session exit.</li>
+</ol>
+<p>Changes propagate to all running shells through an event handler that
+fires whenever __fish_config_op_logging changes — no shell restart
+needed.</p>
+<p>Note: C3 and C5 compose independently. C3 controls whether the
+smart_exit wrapper is active at all; C5 controls only the
+scrollback-capture block inside it. With C3 disabled, exit is plain
+builtin exit regardless of C5.</p>
+<h4 data-number="11.5.1.6" id="c6--greeting-and-first-run-ui">C6 —
+Greeting and First-Run UI</h4>
+<pre><code>Component                  What it shows
+───────────────────────────────────────────────────────────────────────────
+First-run welcome banner   One-time message on first interactive session
+fish_greeting override     Empty function defined late in config.fish to
+                           suppress distro greetings (e.g. CachyOS sets
+                           fish_greeting to fastfetch by default)</code></pre>
+<p>When C6 is disabled, no greeting is printed by this config. Any
+greeting set by the distro or other configs runs normally — this config
+simply does not override it.</p>
 <h2 data-number="11.6" id="prompt-and-theme">Prompt and Theme</h2>
 <h3 data-number="11.6.1" id="starship">Starship</h3>
 <p>The primary prompt is Starship, initialized by conf.d/starship.fish.

docs/html/9-5-functions-reference.html

@@ -589,7 +589,16 @@ Falls back to /usr/bin/rm when trash is unavailable.
 rm file.txt           # moves to trash
 rm -e                 # empty trash
 rm -S sensitive.pem   # permanent delete</code></pre>
-<h3 data-number="9.1.17" id="scrub">scrub</h3>
+<h3 data-number="9.1.17" id="rg">rg</h3>
+<pre><code>Synopsis:  rg [args...]
+In Kitty, wraps ripgrep with --hyperlink-format=kitty so search
+results are clickable file links in the terminal. Falls back to
+system rg in any other terminal. All other arguments pass through
+unchanged.
+
+rg &quot;fish_greeting&quot; ~/.config/fish/
+rg -l &quot;TODO&quot; ~/projects/myapp</code></pre>
+<h3 data-number="9.1.18" id="scrub">scrub</h3>
 <pre><code>Synopsis:  scrub [-a] [-d] [-h]
 Recursively removes OS metadata, editor artifacts, compiler output,
 and dev caches using fd.

docs/html/index.html

@@ -611,6 +611,7 @@ id="toc-mkcd">mkcd</a></li>
 <li><a href="9-5-functions-reference.html#poke"
 id="toc-poke">poke</a></li>
 <li><a href="9-5-functions-reference.html#rm" id="toc-rm">rm</a></li>
+<li><a href="9-5-functions-reference.html#rg" id="toc-rg">rg</a></li>
 <li><a href="9-5-functions-reference.html#scrub"
 id="toc-scrub">scrub</a></li>
 </ul></li>
@@ -821,7 +822,11 @@ id="toc-fish-universal-variables">Fish Universal Variables</a></li>
 <li><a
 href="11-7-customization.html#opinionated-components-minimal-mode"
 id="toc-opinionated-components-minimal-mode">Opinionated Components
-(Minimal Mode)</a></li>
+(Minimal Mode)</a>
+<ul>
+<li><a href="11-7-customization.html#component-reference"
+id="toc-component-reference">Component Reference</a></li>
+</ul></li>
 <li><a href="11-7-customization.html#prompt-and-theme"
 id="toc-prompt-and-theme">Prompt and Theme</a>
 <ul>

docs/wiki/5-functions-reference.md

@@ -135,6 +135,17 @@
     rm -e                 # empty trash
     rm -S sensitive.pem   # permanent delete
 
+### rg
+
+    Synopsis:  rg [args...]
+    In Kitty, wraps ripgrep with --hyperlink-format=kitty so search
+    results are clickable file links in the terminal. Falls back to
+    system rg in any other terminal. All other arguments pass through
+    unchanged.
+
+    rg "fish_greeting" ~/.config/fish/
+    rg -l "TODO" ~/projects/myapp
+
 ### scrub
 
     Synopsis:  scrub [-a] [-d] [-h]

docs/wiki/7-customization.md

@@ -112,6 +112,172 @@ Notes:
   - On CachyOS, the distro fish config's own aliases, history override,
     and bang-bang bindings are stripped per category as well.
 
+### Component Reference
+
+The following tables detail every component in each category. Use this
+reference to understand exactly which behaviors change when you toggle a
+category variable.
+
+#### C1 — Command Shadows
+
+Disabling __fish_config_op_aliases restores standard system behavior for
+all of these commands.
+
+    Command / Alias    Active behavior                       Disabled fallback
+    ───────────────────────────────────────────────────────────────────────────
+    ls                 eza -l -a --icons --hyperlink          system ls
+    cat                bat syntax-highlighted; dirs → ls      /usr/bin/cat
+    cd                 zoxide frecency-based navigation        fish builtin cd
+    rm                 moves files to trash (recoverable)     command rm (permanent)
+    less               $PAGER → ov → less → more → cat       system less
+    du                 duf (disk overview) or dust (dir tree) system du
+    top                btop resource monitor                  system top
+    ping               prettyping --nolegend animation        system ping
+    ssh                kitten ssh in Kitty terminal           system ssh
+    rg                 rg --hyperlink-format=kitty            system rg
+    mkdir              verbose path-tree display on creation  mkdir -p silently
+    bash               XDG bashrc + $SHELL reset on exit      system bash
+    history            timestamps prepended to every entry    fish builtin history
+    cp / mv            forced -i confirmation prompt          cp / mv unmodified
+    wget               forced --continue (resume downloads)   system wget
+    grep/fgrep/egrep   forced --color=auto                    system grep variants
+    dir / vdir         forced --color=auto                    system dir / vdir
+    help config        intercepts "help config" → config-help fish builtin help
+
+When C1 is disabled, `rm` uses bare `command rm` with no wrapper — files
+are permanently deleted, not trashed. There is no intermediate safety net.
+
+#### C2 — Startup Side-Effects
+
+These run automatically without any user action. Disabling
+__fish_config_op_autoexec prevents all of them.
+
+    Component                  Trigger              What it does
+    ───────────────────────────────────────────────────────────────────────────
+    Fisher bootstrap           First shell only     Downloads and installs fisher
+    Fisher update              After bootstrap      Installs all fish_plugins entries
+    Catppuccin Mocha theme     First shell only     Applies theme via fish_config
+    paru wrapper               Every startup        Writes ~/.local/bin/paru wrapper
+    yay wrapper                Every startup        Writes ~/.local/bin/yay wrapper
+    Python venv activation     On every cd          Sources .venv/bin/activate.fish
+    WakaTime command hook      On every command     Reports to WakaTime API
+
+When C2 is disabled: no Fisher install, no theme application, no paru/yay
+wrapper generation, no automatic venv activation, and no WakaTime reporting.
+The first-run completion marker (__fish_config_first_run_complete) is still
+set so the init does not re-run on subsequent shells.
+
+Python venv activation fires on every directory change. If a directory uses
+direnv (.envrc present), direnv takes priority and auto-venv is skipped for
+that directory.
+
+#### C3 — Key and Environment Overrides
+
+These change fundamental shell behavior: how keys work, which pager opens,
+and what the prompt looks like. Disabling __fish_config_op_overrides removes
+all of them.
+
+    Override                  What it replaces or sets
+    ───────────────────────────────────────────────────────────────────────────
+    Vi mode                   fish_vi_key_bindings replaces default Emacs mode
+    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
+    CDPATH=. ~/projects ~     bare dir names resolve against ~/projects and ~
+    Bang-bang system          ! and $ keys expand history; !^, !*, !-N, !?str?,
+                              ^old^new abbreviations; six expand_bang_* helpers
+    Autopair                  ( [ { " ' auto-close to (), [], {}, "", ''
+    Puffer key intercepts     . ! $ * keys intercepted for smart expansion
+    Starship prompt           fish_prompt replaced by Starship + OSC 133 markers
+    Catppuccin colors         30+ fish_color_* variables set to Mocha palette
+    FZF_DEFAULT_OPTS          FZF themed to Catppuccin Mocha colors
+    Right prompt              fish_right_prompt: Docker context + timestamp
+
+The bang-bang system spans key_bindings.fish, abbr.fish, puffer.fish, and
+six expand_bang_*.fish functions. All are gated together — disabling C3
+removes the entire bang-expansion system at once.
+
+When C3 is disabled, `exit` falls back to `builtin exit` with no scrollback
+capture, no Kitty IPC, and no file I/O on exit. The scrollback capture block
+is independently controlled by C5 (see below).
+
+#### C4 — Terminal and Tool Integration
+
+These features couple the shell to specific external tools. Disabling
+__fish_config_op_integrations disables all of them.
+
+    Component                  Requires
+    ───────────────────────────────────────────────────────────────────────────
+    ~60 Kitty/WezTerm abbrs    Active Kitty or WezTerm session
+      (:w, :wv, :wh, :t, etc.)
+    Done desktop notifications Graphical desktop with a notification daemon
+    spwin                      Kitty or WezTerm
+    tab                        Kitty, WezTerm, or Konsole
+    split                      Kitty or WezTerm
+    hist                       fzf + wl-copy (Wayland clipboard)
+    logs                       fzf + ov; reads from ~/.terminal_history/
+    upgrade                    paru or yay (Arch Linux only)
+    WakaTime hook              wakatime CLI and a configured API key
+
+Disabled integration commands (spwin, tab, split, hist, logs, upgrade) print
+a colored error to stderr naming the variable that disabled them rather than
+silently failing.
+
+#### C5 — Logging and Capture
+
+Three components capture shell output to disk. Disabling
+__fish_config_op_logging skips all capture and removes the logging wrappers.
+
+    Component               What it captures
+    ───────────────────────────────────────────────────────────────────────────
+    Scrollback capture      Terminal session output saved to:
+                            ~/.terminal_history/scrollback_YYYY-MM-DD_HH-MM-SS.log
+    paru wrapper            All paru/AUR output teed to:
+                            ~/.terminal_history/paru_YYYY-MM-DD_HH-MM-SS.log
+    yay wrapper             All yay/AUR output teed to:
+                            ~/.terminal_history/yay_YYYY-MM-DD_HH-MM-SS.log
+    Kitty watcher           watcher.py captures scrollback when Kitty closes
+
+Logging coordination via sentinel file
+
+C5 uses a sentinel file to synchronize state between the shell and
+out-of-process components (the Kitty watcher and all running shells):
+
+    ~/.config/fish/.logging_disabled
+
+Disabling __fish_config_op_logging:
+  1. Creates the sentinel immediately in every open shell.
+  2. Removes ~/.local/bin/paru and ~/.local/bin/yay logging wrappers;
+     bare /usr/bin/paru and /usr/bin/yay are used instead.
+  3. Kitty's watcher.py reads the sentinel on each save attempt and
+     skips capture — no Kitty restart required.
+  4. smart_exit stops saving scrollback logs.
+
+Re-enabling __fish_config_op_logging:
+  1. Removes the sentinel in every open shell.
+  2. Regenerates paru/yay logging wrappers in ~/.local/bin/.
+  3. Kitty watcher resumes capture on the next session exit.
+
+Changes propagate to all running shells through an event handler that fires
+whenever __fish_config_op_logging changes — no shell restart needed.
+
+Note: C3 and C5 compose independently. C3 controls whether the smart_exit
+wrapper is active at all; C5 controls only the scrollback-capture block
+inside it. With C3 disabled, exit is plain builtin exit regardless of C5.
+
+#### C6 — Greeting and First-Run UI
+
+    Component                  What it shows
+    ───────────────────────────────────────────────────────────────────────────
+    First-run welcome banner   One-time message on first interactive session
+    fish_greeting override     Empty function defined late in config.fish to
+                               suppress distro greetings (e.g. CachyOS sets
+                               fish_greeting to fastfetch by default)
+
+When C6 is disabled, no greeting is printed by this config. Any greeting
+set by the distro or other configs runs normally — this config simply does
+not override it.
+
 ## Prompt and Theme
 
 ### Starship