feat(logging)!: make C5 session logging opt-in

Session logging is the one opinionated category that writes a persistent
record of terminal output to disk, and those logs can contain secrets.
Silent-by-default is the wrong posture for it, so C5 now defaults to off:
__fish_config_op_logging must be set to an explicit truthy value to enable
capture, and the master switch cannot enable it on its own.

Implemented as a single special case in __fish_config_op_enabled, so all
five capture components, the sentinel file, the paru/yay wrappers, the
Kitty watcher, and the config-settings TUI pick it up with no other code
changes. The existing startup sync in conf.d/logging-events.fish
reconciles the sentinel and removes the generated wrappers on the first
shell after upgrading.

BREAKING CHANGE: users relying on the previous default must now run
`set -U __fish_config_op_logging on`. Existing logs in ~/.terminal_history
are left untouched.

README.md

@@ -30,23 +30,24 @@ This config layers on top of the CachyOS base Fish configuration and adds:
 - **Smart CLI wrappers** that prefer modern tools (`eza`, `bat`, `btop`, `dust`, `prettyping`) with graceful fallbacks
 - **Auto Python venv** activation on directory change (direnv-aware)
 - **Kitty terminal** deep integration for splits, tabs, and SSH
-- **Automatic session logging** — terminal scrollback, multiplexer panes (tmux/zellij), and AUR-helper output are captured to `~/.terminal_history` (see the caution below and [Session Logging](#session-logging))
+- **Optional session logging** — terminal scrollback, multiplexer panes (tmux/zellij), and AUR-helper output can be captured to `~/.terminal_history`; **off by default**, opt in when you want it (see the caution below and [Session Logging](#session-logging))
 - **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)
 
 > [!CAUTION]
-> **This configuration logs your terminal sessions to disk by default.**
+> **This configuration *can* log your terminal sessions to disk.** Logging is
-> Out of the box it silently captures terminal output to `~/.terminal_history`:
+> **off by default** — but once enabled it silently captures terminal output to
-> Kitty scrollback when a window closes, live tmux pane streams, zellij pane
+> `~/.terminal_history`: Kitty scrollback when a window closes, live tmux pane
-> snapshots on exit, and full `paru`/`yay` output. These logs can contain
+> streams, zellij pane snapshots on exit, and full `paru`/`yay` output. These
-> command output, file contents, and anything else printed to your terminal.
+> logs can contain command output, file contents, and anything else printed to
-> Nothing is sent off your machine, but the files persist locally until pruned.
+> your terminal. Nothing is sent off your machine, but the files persist
+> locally until pruned.
 >
-> To turn all logging off, set the C5 category variable:
+> To turn logging on, set the C5 category variable:
 >
 > ```fish
-> set -U __fish_config_op_logging off
+> set -U __fish_config_op_logging on
 > ```
 >
 > Or run **`config-settings`** for an interactive menu to flip logging (and any
@@ -60,9 +61,10 @@ This config layers on top of the CachyOS base Fish configuration and adds:
 
 ## Session Logging
 
-This config captures terminal output to `~/.terminal_history` (override with
+This config can capture terminal output to `~/.terminal_history` (override with
 `$SCROLLBACK_HISTORY_DIR`) so you can search back through past sessions. It is
-**on by default**. Five sources feed it:
+**off by default** — opt in with `set -U __fish_config_op_logging on`. Once
+enabled, five sources feed it:
 
 | Source | When it captures | Log file |
 |---|---|---|
@@ -84,21 +86,26 @@ Old logs are pruned automatically to stay within `$SCROLLBACK_HISTORY_MAX_FILES`
 output, file dumps, tokens echoed to stdout) ends up in them. They never leave
 your machine, but treat `~/.terminal_history` as sensitive.
 
-Disable all of it with a single universal variable:
+All of it is controlled by a single universal variable:
 
 ```fish
-set -U __fish_config_op_logging off   # disable; takes effect in every open shell
+set -U __fish_config_op_logging on    # enable; takes effect in every open shell
-set -Ue __fish_config_op_logging      # re-enable (erase the override)
+set -U __fish_config_op_logging off   # disable again
+set -Ue __fish_config_op_logging      # erase — back to the default (off)
 ```
 
+Unlike the other categories, C5 is opt-in: an unset variable means off, and
+`__fish_config_opinionated` cannot turn it on for you.
+
 Prefer an interactive interface? Run **`config-settings`** for a full-screen
 picker that flips logging — and every other opinionated category — on or off
 per session or universally, without memorizing variable names.
 
-Disabling also removes the generated `paru`/`yay` log wrappers and tells the
+Disabling (or leaving it unset) also removes the generated `paru`/`yay` log
-Kitty watcher to skip capture via a sentinel file — no shell or terminal
+wrappers and tells the Kitty watcher to skip capture via a sentinel file — no
-restart required. Logging is category **C5** in [Minimal Mode](#minimal-mode);
+shell or terminal restart required. Logging is category **C5** in
-`set -U __fish_config_opinionated 0` turns it off along with everything else.
+[Minimal Mode](#minimal-mode); `set -U __fish_config_opinionated 0` keeps it
+off along with everything else.
 
 The Kitty scrollback capture is provided by a watcher script that fish-config can
 install and manage for you. Inside Kitty, if it isn't set up yet, you'll see a
@@ -113,8 +120,9 @@ one-time-per-session reminder. Manage it with:
 
 `install` adds a clearly-marked managed block to `kitty.conf` and comments out
 any conflicting `watcher` line. It affects **new** Kitty windows (existing
-windows keep their current watcher until restarted). Disabling C5 logging makes
+windows keep their current watcher until restarted). With C5 logging off the
-the watcher inert without uninstalling it.
+watcher is inert without needing to be uninstalled, and the reminder stays
+silent until you enable logging.
 
 ---
 
@@ -269,7 +277,7 @@ To opt out, set `__fish_user_dots_symlink` to a falsy value (or toggle **Dots li
 
 ## Minimal Mode
 
-Everything opinionated in this config — command shadows, startup side-effects, key and environment overrides, terminal integrations, logging, and the first-run greeting — is active by default but can be switched off.
+Everything opinionated in this config — command shadows, startup side-effects, key and environment overrides, terminal integrations, and the first-run greeting — is active by default but can be switched off. Logging (C5) is the exception: it is **opt-in**, off until you explicitly enable it.
 
 > **The easy way — `config-settings`:** Run `config-settings` for an interactive TUI that manages settings across four pages — **Universal** and **Session** (the opinionated category toggles below, persistent or per-shell), **Sponge** (history-scrubbing: delay, exit codes, purge-on-exit, and extra sensitive variable names), and **Paths** (scrollback log dir, max files, and the user-dots path) — without typing a single variable name. Navigate with the arrow keys (or `h`/`j`/`k`/`l`); toggle rows step OFF ← DEFAULT → ON, value rows edit inline with `Enter` and clear with `←`. `Tab`/`Shift-Tab` cycle pages and `q` quits. Changes apply instantly. The panel auto-sizes to your terminal width (four tiers from 52- to 78-wide with a 6-column margin), centers itself horizontally, and redraws within ~0.3 s of a resize.
 
@@ -281,9 +289,9 @@ If you'd rather set them by hand, each category is controlled by a universal var
 | `__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`/`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_logging` | **Opt-in — off unless explicitly enabled.** 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 |
-| `__fish_config_opinionated` | Master switch — all six categories at once |
+| `__fish_config_opinionated` | Master switch — disables all six categories at once (it is a master *off* switch; it cannot enable opt-in C5 logging) |
 
 Set any of them to a falsy value (`0`, `false`, `no`, `off`, `n`) to disable; erase the variable to re-enable. An explicit per-category truthy value overrides a falsy master switch, so you can disable everything with `__fish_config_opinionated=0` and selectively re-enable individual categories:
 
@@ -298,6 +306,9 @@ set -U __fish_config_op_aliases off
 set -U __fish_config_opinionated 0
 set -U __fish_config_op_greeting 1
 
+# Opt in to session logging (C5 is off by default)
+set -U __fish_config_op_logging on
+
 # Back to full flavor
 set -Ue __fish_config_opinionated
 set -Ue __fish_config_op_greeting

config.fish

@@ -15,8 +15,11 @@
 #   __fish_config_op_overrides     C3 — key bindings, env, prompt overrides
 #   __fish_config_op_integrations  C4 — terminal/tool coupling
 #   __fish_config_op_logging       C5 — scrollback capture / AUR log wrappers
+#                                       (opt-in: unset means OFF)
 #   __fish_config_op_greeting      C6 — per-session greeting / first-run welcome
 # Example: set -U __fish_config_op_aliases off   (erase to re-enable)
+# C5 is the one exception: it defaults to disabled and needs an explicit
+# truthy value — set -U __fish_config_op_logging on
 
 #   ──────────────────────── Source CachyOS configs ────────────────────────
 if test -f /usr/share/cachyos-fish-config/cachyos-config.fish

docs/fish-config.index

@@ -296,7 +296,8 @@ uninstall=## Uninstalling and Reverting to Backup
 revert=## Uninstalling and Reverting to Backup
 fish-version=## Fish Version Requirement
 version-req=## Fish Version Requirement
-disable-logging=## Disable Session Logging
+disable-logging=## Enable or Disable Session Logging
+enable-logging=## Enable or Disable Session Logging
 disable-greeting=## Change or Disable the Greeting
 change-greeting=## Change or Disable the Greeting
 secrets-trouble=## Secrets and Machine-Local Configuration

docs/fish-config.md

@@ -32,21 +32,23 @@ A production-grade Fish shell configuration targeting Fish 4.x. It provides:
 - Drop-in replacements for common Unix tools (ls, cat, rm, du, ping, less)
 - Deep Kitty and WezTerm terminal integration: tab/window/pane management from
   the command line
-- Automatic session logging: terminal scrollback, tmux/zellij panes, and
+- Optional session logging: terminal scrollback, tmux/zellij panes, and
-  paru/yay output captured to ~/.terminal_history (on by default; see below)
+  paru/yay output captured to ~/.terminal_history (off by default; see below)
 - Automatic Python virtualenv activation on directory change
 - Cross-platform package management via pkg and fish-deps
 - AI scaffolding helpers for Claude Code and Antigravity
 - Catppuccin Mocha color theme throughout
 
-CAUTION: **SESSION LOGGING IS ON BY DEFAULT**  
+CAUTION: **SESSION LOGGING IS OPT-IN**  
-This configuration silently records terminal output to `~/.terminal_history`:
+Once enabled, this configuration *can* silently record terminal output to
-Kitty scrollback on window close, live tmux pane streams, zellij pane
+`~/.terminal_history`: Kitty scrollback on window close, live tmux pane
-snapshots on exit, and full paru/yay output. These logs can contain command
+streams, zellij pane snapshots on exit, and full paru/yay output. These logs
-output, file contents, and secrets printed to the terminal. Nothing leaves
+can contain command output, file contents, and secrets printed to the
-your machine, but the files persist locally.
+terminal. Nothing leaves your machine, but the files persist locally. Logging
-- Disable all logging with: `set -U __fish_config_op_logging off`
+is off unless you turn it on.
+- Enable all logging with: `set -U __fish_config_op_logging on`
 - Prefer a menu? Run the interactive picker: `config-settings`
+- Turn it back off with: `set -U __fish_config_op_logging off` (or erase the variable)
 - See C5 — Logging and Capture for the full breakdown.
 
 The configuration uses a structured file tree:
@@ -130,7 +132,7 @@ The configuration uses a structured file tree:
     11. Troubleshooting
         11.1 Uninstalling and Reverting to Backup
         11.2 Fish Version Requirement
-        11.3 Disable Session Logging
+        11.3 Enable or Disable Session Logging
         11.4 Change or Disable the Greeting
         11.5 Secrets and Machine-Local Configuration
         11.6 Tool Init Does Nothing (Return Sentinel)
@@ -2565,12 +2567,18 @@ Every opinionated piece of this config is active by default but can be
 switched off through six 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.
+yes, on, y) to re-enable. Unset means enabled — except for C5 logging, which
+is opt-in (see below).
 
 An explicit per-category truthy value takes precedence over the master
 switch: setting __fish_config_opinionated=0 disables all unset categories,
 but a category with an explicit truthy value remains enabled regardless.
 
+C5 (logging) is the one exception to "unset means enabled". Because it
+writes terminal output to disk, it is opt-in: unset means disabled, and the
+master switch cannot enable it. Only an explicit truthy value turns logging
+on.
+
     Variable                        Disables
     ────────────────────────────────────────
     __fish_config_op_aliases        Command shadows and flag injection:
@@ -2595,10 +2603,11 @@ but a category with an explicit truthy value remains enabled regardless.
                                     WezTerm window abbreviations, done
                                     notifications, spwin/tab/split,
                                     hist, logs, upgrade, WakaTime
-    __fish_config_op_logging        Logging & capture: scrollback
+    __fish_config_op_logging        Logging & capture (OPT-IN — this one
-                                    capture on exit, paru/yay AUR log
+                                    is off unless explicitly enabled):
-                                    wrappers, Kitty watcher capture;
+                                    scrollback capture on exit, paru/yay
-                                    sentinel file coordinates
+                                    AUR log wrappers, Kitty watcher
+                                    capture; sentinel file coordinates
                                     cross-process state
     __fish_config_op_greeting       Greeting & first-run UI: per-session
                                     fish_greeting override (defines empty
@@ -2612,10 +2621,13 @@ Examples:
     # Disable command shadows only (rm becomes plain rm again):
     set -U __fish_config_op_aliases off
 
+    # Turn session logging on (opt-in; off until you do this):
+    set -U __fish_config_op_logging on
+
     # Full minimal mode — disable all six categories at once:
     set -U __fish_config_opinionated 0
 
-    # Re-enable everything:
+    # Re-enable everything (except C5 logging, which stays opt-in):
     set -Ue __fish_config_opinionated
 
     # Minimal mode but keep the greeting:
@@ -2769,8 +2781,16 @@ silently failing.
 
 #### C5 — Logging and Capture
 
-Five components capture shell output to disk. Disabling
+Five components capture shell output to disk. Unlike every other category,
-__fish_config_op_logging skips all capture and removes the logging wrappers.
+C5 is opt-in: it stays off until __fish_config_op_logging is set to an
+explicit truthy value, and a truthy master switch does not enable it. While
+it is off, all capture is skipped and the logging wrappers are removed.
+
+    # Turn it on (persistently, in every shell):
+    set -U __fish_config_op_logging on
+
+    # Turn it back off:
+    set -U __fish_config_op_logging off     # or: set -Ue __fish_config_op_logging
 
     Component               What it captures
     ───────────────────────────────────────────────────────────────────────────
@@ -2827,8 +2847,10 @@ The Kitty watcher is managed by the kitty-logging command: it symlinks the
 watcher (fish-config-watcher.py) into the Kitty config directory and wires it
 into kitty.conf via a managed block. Inside Kitty, a non-blocking
 per-session reminder points first-time users at `kitty-logging install` until
-they install or run `kitty-logging dismiss`. Install affects new Kitty windows
+they install or run `kitty-logging dismiss`; the reminder is itself gated on
-only; runtime disable is still handled by the .logging_disabled sentinel.
+C5, so it stays silent until you enable logging. Install affects new Kitty
+windows only; runtime disable is still handled by the .logging_disabled
+sentinel.
 
 Logging coordination via sentinel file
 
@@ -2837,7 +2859,11 @@ out-of-process components (the Kitty watcher and all running shells):
 
     ~/.config/fish/.logging_disabled
 
-Disabling __fish_config_op_logging:
+Because C5 is off by default, the sentinel is present on a fresh install —
+the startup sync in conf.d/logging-events.fish reconciles it on every shell
+start, so it appears without any action on your part.
+
+Disabling __fish_config_op_logging (or leaving it unset):
   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.
@@ -2846,7 +2872,7 @@ Disabling __fish_config_op_logging:
   4. smart_exit stops saving scrollback logs.
   5. Stops tmux pipe-pane capture in every open fish shell inside tmux.
 
-Re-enabling __fish_config_op_logging:
+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.
@@ -3198,22 +3224,25 @@ Upgrading Fish by distribution:
 
 For other systems or building from source, see https://fishshell.com.
 
-## Disable Session Logging
+## Enable or Disable Session Logging
 
-Disable all logging and capture (scrollback, tmux/zellij pane logs, AUR
+Session logging is opt-in: it is off until you turn it on. To enable all
-helper wrappers, Kitty watcher):
+logging and capture (scrollback, tmux/zellij pane logs, AUR helper wrappers,
+Kitty watcher):
 
-    set -U __fish_config_op_logging off
+    set -U __fish_config_op_logging on
 
 Or toggle it interactively: run `config-settings` and flip the Logging row.
 
+Disable it again — either an explicit falsy value or erasing the variable
+returns you to the default off state:
+
+    set -U __fish_config_op_logging off
+    set -Ue __fish_config_op_logging
+
 This takes effect immediately in all running shells — no restart needed. The
 sentinel file, wrapper removal, and pipe-pane teardown happen automatically.
 
-Re-enable:
-
-    set -Ue __fish_config_op_logging
-
 See C5 — Logging and Capture for the full component breakdown.
 
 ## Change or Disable the Greeting
@@ -3345,7 +3374,7 @@ Disable a single category:
     set -U __fish_config_op_autoexec off        # C2
     set -U __fish_config_op_overrides off       # C3
     set -U __fish_config_op_integrations off    # C4
-    set -U __fish_config_op_logging off         # C5
+    set -U __fish_config_op_logging off         # C5 (already off by default)
     set -U __fish_config_op_greeting off        # C6
 
 Keep one category active under a master disable:

docs/manual/00-table-of-contents.md

@@ -45,7 +45,7 @@ sidebar:
     11. Troubleshooting
         11.1 Uninstalling and Reverting to Backup
         11.2 Fish Version Requirement
-        11.3 Disable Session Logging
+        11.3 Enable or Disable Session Logging
         11.4 Change or Disable the Greeting
         11.5 Secrets and Machine-Local Configuration
         11.6 Tool Init Does Nothing (Return Sentinel)

docs/manual/07-customization.md

@@ -62,12 +62,18 @@ Every opinionated piece of this config is active by default but can be
 switched off through six 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.
+yes, on, y) to re-enable. Unset means enabled — except for C5 logging, which
+is opt-in (see below).
 
 An explicit per-category truthy value takes precedence over the master
 switch: setting __fish_config_opinionated=0 disables all unset categories,
 but a category with an explicit truthy value remains enabled regardless.
 
+C5 (logging) is the one exception to "unset means enabled". Because it
+writes terminal output to disk, it is opt-in: unset means disabled, and the
+master switch cannot enable it. Only an explicit truthy value turns logging
+on.
+
     Variable                        Disables
     ────────────────────────────────────────
     __fish_config_op_aliases        Command shadows and flag injection:
@@ -92,10 +98,11 @@ but a category with an explicit truthy value remains enabled regardless.
                                     WezTerm window abbreviations, done
                                     notifications, spwin/tab/split,
                                     hist, logs, upgrade, WakaTime
-    __fish_config_op_logging        Logging & capture: scrollback
+    __fish_config_op_logging        Logging & capture (OPT-IN — this one
-                                    capture on exit, paru/yay AUR log
+                                    is off unless explicitly enabled):
-                                    wrappers, Kitty watcher capture;
+                                    scrollback capture on exit, paru/yay
-                                    sentinel file coordinates
+                                    AUR log wrappers, Kitty watcher
+                                    capture; sentinel file coordinates
                                     cross-process state
     __fish_config_op_greeting       Greeting & first-run UI: per-session
                                     fish_greeting override (defines empty
@@ -109,10 +116,13 @@ Examples:
     # Disable command shadows only (rm becomes plain rm again):
     set -U __fish_config_op_aliases off
 
+    # Turn session logging on (opt-in; off until you do this):
+    set -U __fish_config_op_logging on
+
     # Full minimal mode — disable all six categories at once:
     set -U __fish_config_opinionated 0
 
-    # Re-enable everything:
+    # Re-enable everything (except C5 logging, which stays opt-in):
     set -Ue __fish_config_opinionated
 
     # Minimal mode but keep the greeting:
@@ -266,8 +276,16 @@ silently failing.
 
 #### C5 — Logging and Capture
 
-Five components capture shell output to disk. Disabling
+Five components capture shell output to disk. Unlike every other category,
-__fish_config_op_logging skips all capture and removes the logging wrappers.
+C5 is opt-in: it stays off until __fish_config_op_logging is set to an
+explicit truthy value, and a truthy master switch does not enable it. While
+it is off, all capture is skipped and the logging wrappers are removed.
+
+    # Turn it on (persistently, in every shell):
+    set -U __fish_config_op_logging on
+
+    # Turn it back off:
+    set -U __fish_config_op_logging off     # or: set -Ue __fish_config_op_logging
 
     Component               What it captures
     ───────────────────────────────────────────────────────────────────────────
@@ -324,8 +342,10 @@ The Kitty watcher is managed by the kitty-logging command: it symlinks the
 watcher (fish-config-watcher.py) into the Kitty config directory and wires it
 into kitty.conf via a managed block. Inside Kitty, a non-blocking
 per-session reminder points first-time users at `kitty-logging install` until
-they install or run `kitty-logging dismiss`. Install affects new Kitty windows
+they install or run `kitty-logging dismiss`; the reminder is itself gated on
-only; runtime disable is still handled by the .logging_disabled sentinel.
+C5, so it stays silent until you enable logging. Install affects new Kitty
+windows only; runtime disable is still handled by the .logging_disabled
+sentinel.
 
 Logging coordination via sentinel file
 
@@ -334,7 +354,11 @@ out-of-process components (the Kitty watcher and all running shells):
 
     ~/.config/fish/.logging_disabled
 
-Disabling __fish_config_op_logging:
+Because C5 is off by default, the sentinel is present on a fresh install —
+the startup sync in conf.d/logging-events.fish reconciles it on every shell
+start, so it appears without any action on your part.
+
+Disabling __fish_config_op_logging (or leaving it unset):
   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.
@@ -343,7 +367,7 @@ Disabling __fish_config_op_logging:
   4. smart_exit stops saving scrollback logs.
   5. Stops tmux pipe-pane capture in every open fish shell inside tmux.
 
-Re-enabling __fish_config_op_logging:
+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.

docs/manual/11-troubleshooting.md

@@ -75,22 +75,25 @@ Upgrading Fish by distribution:
 
 For other systems or building from source, see https://fishshell.com.
 
-## Disable Session Logging
+## Enable or Disable Session Logging
 
-Disable all logging and capture (scrollback, tmux/zellij pane logs, AUR
+Session logging is opt-in: it is off until you turn it on. To enable all
-helper wrappers, Kitty watcher):
+logging and capture (scrollback, tmux/zellij pane logs, AUR helper wrappers,
+Kitty watcher):
 
-    set -U __fish_config_op_logging off
+    set -U __fish_config_op_logging on
 
 Or toggle it interactively: run `config-settings` and flip the Logging row.
 
+Disable it again — either an explicit falsy value or erasing the variable
+returns you to the default off state:
+
+    set -U __fish_config_op_logging off
+    set -Ue __fish_config_op_logging
+
 This takes effect immediately in all running shells — no restart needed. The
 sentinel file, wrapper removal, and pipe-pane teardown happen automatically.
 
-Re-enable:
-
-    set -Ue __fish_config_op_logging
-
 See [C5 — Logging and Capture](/07-customization/#c5-logging-and-capture) for the full component breakdown.
 
 ## Change or Disable the Greeting
@@ -222,7 +225,7 @@ Disable a single category:
     set -U __fish_config_op_autoexec off        # C2
     set -U __fish_config_op_overrides off       # C3
     set -U __fish_config_op_integrations off    # C4
-    set -U __fish_config_op_logging off         # C5
+    set -U __fish_config_op_logging off         # C5 (already off by default)
     set -U __fish_config_op_greeting off        # C6
 
 Keep one category active under a master disable:

docs/manual/index.md

@@ -17,8 +17,8 @@ A production-grade Fish shell configuration targeting Fish 4.x. It provides:
 - Drop-in replacements for common Unix tools (ls, cat, rm, du, ping, less)
 - Deep Kitty and WezTerm terminal integration: tab/window/pane management from
   the command line
-- Automatic session logging: terminal scrollback, tmux/zellij panes, and
+- Optional session logging: terminal scrollback, tmux/zellij panes, and
-  paru/yay output captured to ~/.terminal_history (on by default; see below)
+  paru/yay output captured to ~/.terminal_history (off by default; see below)
 - Automatic Python virtualenv activation on directory change
 - Cross-platform package management via pkg and fish-deps
 - AI scaffolding helpers for Claude Code and Antigravity
@@ -27,14 +27,16 @@ A production-grade Fish shell configuration targeting Fish 4.x. It provides:
 <LinkButton href="/09-installation/">Install now</LinkButton>
 <LinkButton href="/reference/" variant="secondary">Function reference</LinkButton>
 
-CAUTION: **SESSION LOGGING IS ON BY DEFAULT**  
+CAUTION: **SESSION LOGGING IS OPT-IN**  
-This configuration silently records terminal output to `~/.terminal_history`:
+Once enabled, this configuration *can* silently record terminal output to
-Kitty scrollback on window close, live tmux pane streams, zellij pane
+`~/.terminal_history`: Kitty scrollback on window close, live tmux pane
-snapshots on exit, and full paru/yay output. These logs can contain command
+streams, zellij pane snapshots on exit, and full paru/yay output. These logs
-output, file contents, and secrets printed to the terminal. Nothing leaves
+can contain command output, file contents, and secrets printed to the
-your machine, but the files persist locally.
+terminal. Nothing leaves your machine, but the files persist locally. Logging
-- Disable all logging with: `set -U __fish_config_op_logging off`
+is off unless you turn it on.
+- Enable all logging with: `set -U __fish_config_op_logging on`
 - Prefer a menu? Run the interactive picker: `config-settings`
+- Turn it back off with: `set -U __fish_config_op_logging off` (or erase the variable)
 - See [C5 — Logging and Capture](/07-customization/#c5-logging-and-capture) for the full breakdown.
 
 The configuration uses a structured file tree:

functions/__fish_config_op_enabled.fish

@@ -15,6 +15,11 @@
 #   falsy master disables every unset-category component at once.
 #   Unset master with unset category → enabled (active by default).
 #
+#   One exception: __fish_config_op_logging (C5) is opt-in, because it
+#   writes terminal output to disk. Unset or unrecognized means disabled,
+#   and the master switch cannot enable it — only an explicit truthy
+#   value turns logging on.
+#
 # ARGUMENTS
 #   category_variable  Name (without $) of the category opt-out variable:
 #                      __fish_config_op_aliases, __fish_config_op_autoexec,
@@ -24,8 +29,8 @@
 #                      __fish_config_op_greeting
 #
 # EXIT STATUS
-#   0  Component enabled (category explicitly truthy; or category unset and master not falsy)
+#   0  Component enabled (category explicitly truthy; or category unset and master not falsy — except C5 logging, which requires an explicit truthy value)
-#   1  Component disabled (category explicitly falsy; or category unset and master falsy; or no argument with falsy master)
+#   1  Component disabled (category explicitly falsy; or category unset and master falsy; or C5 logging unset; or no argument with falsy master)
 #
 # EXAMPLE
 #   if __fish_config_op_enabled __fish_config_op_aliases
@@ -43,6 +48,12 @@ function __fish_config_op_enabled --description 'Check whether an opinionated co
         return 1
     end
 
+    # C5 logging is opt-in: it writes terminal output to disk, so an unset or
+    # unrecognized value means off — the master switch cannot enable it.
+    if test "$argv[1]" = __fish_config_op_logging
+        return 1
+    end
+
     # Status 3 (garbage) defers to master — an unrecognized value is not an opt-out.
     __fish_variable_check __fish_config_opinionated
     if test $status -eq 1