docs: add Section 11 — Troubleshooting

Add a new Troubleshooting section to the manual with 9 concise how-to
subsections covering uninstall/revert, Fish version requirements,
disabling logging, changing the greeting, secrets/local config, the
return sentinel gotcha, missing dependencies, Vi mode keybindings,
and minimal mode.

Renumber Viewing This Manual from Section 11 to Section 12 to place
troubleshooting before it. Update TOC and help index accordingly.

All verify-manual.py checks pass.

docs/fish-config.index

@@ -288,9 +288,30 @@ personalize=# 10. PERSONALIZATION
 secrets-file=## secrets.fish
 local-config=## local.fish
 
-# ── Section 11: Viewing This Manual ──────────────────────────
+# ── Section 11: Troubleshooting ──────────────────────────────
-viewing=# 11. VIEWING THIS MANUAL
+troubleshooting=# 11. TROUBLESHOOTING
-manual=# 11. VIEWING THIS MANUAL
+troubleshoot=# 11. TROUBLESHOOTING
+faq=# 11. TROUBLESHOOTING
+uninstall=## Uninstalling / Reverting to Backup
+revert=## Uninstalling / Reverting to Backup
+fish-version=## Fish Version Requirement
+version-req=## Fish Version Requirement
+disable-logging=## Disable Session Logging
+disable-greeting=## Change or Disable the Greeting
+change-greeting=## Change or Disable the Greeting
+secrets-trouble=## Secrets and Machine-Local Configuration
+local-trouble=## Secrets and Machine-Local Configuration
+return-sentinel=## Tool Init Does Nothing (Return Sentinel)
+tool-init=## Tool Init Does Nothing (Return Sentinel)
+missing-deps=## Missing Dependencies
+vi-mode=## Vi Mode Keybindings
+vi-trouble=## Vi Mode Keybindings
+emacs-mode=## Vi Mode Keybindings
+minimal-trouble=## Minimal Mode / Disabling Opinionated Features
+
+# ── Section 12: Viewing This Manual ──────────────────────────
+viewing=# 12. VIEWING THIS MANUAL
+manual=# 12. VIEWING THIS MANUAL
 ov=## In the terminal
 man-page=## As a man page
 manpage=## As a man page
@@ -298,3 +319,5 @@ jump=## In the terminal
 html=## The documentation website
 browser=## The documentation website
 site=## The documentation website
+
+

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

@@ -42,6 +42,16 @@ sidebar:
     8.  Fisher Plugins
     9.  Installation
     10. Personalization
-    11. Viewing This Manual
+    11. Troubleshooting
+        11.1 Uninstalling / Reverting to Backup
+        11.2 Fish Version Requirement
+        11.3 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)
+        11.7 Missing Dependencies
+        11.8 Vi Mode Keybindings
+        11.9 Minimal Mode / Disabling Opinionated Features
+    12. Viewing This Manual
 
 ---

docs/manual/11-troubleshooting.md

@@ -0,0 +1,233 @@
+---
+title: Troubleshooting
+manTitle: 11. TROUBLESHOOTING
+sidebar:
+  order: 15
+helpKeywords:
+- troubleshooting
+- troubleshoot
+- faq
+- help
+- uninstall
+- revert
+---
+
+## Uninstalling / Reverting to Backup
+
+The installation step backs up any existing config to `~/.config/fish.bak`.
+To revert:
+
+    rm -rf ~/.config/fish
+    mv ~/.config/fish.bak ~/.config/fish
+
+If no backup exists, remove the directory and let Fish regenerate a default
+config on next launch:
+
+    rm -rf ~/.config/fish
+    fish -c 'fish_config theme choose "Fish default"'
+
+Clean up files generated outside the config directory:
+
+    rm -f ~/.local/bin/paru ~/.local/bin/yay        # AUR log wrappers
+    rm -f ~/.local/share/man/man1/fish-config.1     # man page symlink
+    rm -f ~/.config/fish/.logging_disabled           # C5 sentinel
+
+Erase universal variables set by this config:
+
+    for v in (set -Un | string match '__fish_config*')
+        set -Ue $v
+    end
+    for v in __done_min_cmd_duration __done_notification_urgency_level
+        set -Ue $v
+    end
+    for v in (set -Un | string match 'sponge_*')
+        set -Ue $v
+    end
+
+The `~/.terminal_history/` log directory contains your session logs. Remove
+it only if you do not want to keep them.
+
+## Fish Version Requirement
+
+This config requires Fish 4.x or newer. Check your version:
+
+    fish --version
+
+Run `fish-deps` to see a status report — an outdated Fish shows ⚠ with an
+upgrade message.
+
+Upgrading Fish by distribution:
+
+    # Arch / AUR
+    pacman -S fish          # or paru -S fish
+
+    # Ubuntu / Debian (PPA)
+    sudo apt-add-repository ppa:fish-shell/release-4
+    sudo apt update && sudo apt install fish
+
+    # Fedora
+    sudo dnf install fish
+
+    # macOS
+    brew install fish
+
+For other systems or building from source, see https://fishshell.com.
+
+## Disable Session Logging
+
+Disable all logging and capture (scrollback, tmux/zellij pane logs, AUR
+helper wrappers, Kitty watcher):
+
+    set -U __fish_config_op_logging off
+
+Or toggle it interactively: run `config-settings` and flip the Logging row.
+
+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 Section 7, "C5 — Logging and Capture" for the full component breakdown.
+
+## Change or Disable the Greeting
+
+This config suppresses the distro greeting (e.g. CachyOS fastfetch) by
+default. To let the distro greeting through:
+
+    set -U __fish_config_op_greeting off
+
+To set a custom greeting, define fish_greeting in your local.fish:
+
+    # in $__fish_user_dots_path/local.fish
+    function fish_greeting
+        echo "Hello, world!"
+    end
+
+The first-run welcome banner runs exactly once. To re-trigger it (e.g. for
+testing):
+
+    set -Ue __fish_config_first_run_complete
+
+See Section 7, "C6 — Greeting and First-Run UI" for details.
+
+## Secrets and Machine-Local Configuration
+
+Machine-specific config goes in `$__fish_user_dots_path/local.fish` (defaults
+to `~/.config/.user-dots/fish/local.fish`). Secrets go in `secrets.fish` in
+the same directory.
+
+If local.fish is not loading, verify the path:
+
+    echo $__fish_user_dots_path
+    test -f "$__fish_user_dots_path/local.fish"; and echo exists; or echo missing
+
+Change the path via variable or TUI:
+
+    set -U __fish_user_dots_path /new/path/to/dots/fish
+
+Or run `config-settings`, navigate to the Paths page, and edit "Dots path".
+
+The `user-dots` convenience symlink in the config directory tracks this path.
+Disable it with:
+
+    set -U __fish_user_dots_symlink false
+
+See Section 10, "Personalization" for the full local.fish / secrets.fish
+layout.
+
+## Tool Init Does Nothing (Return Sentinel)
+
+Symptom: you ran a tool's setup command (e.g.
+`starship init fish >> ~/.config/fish/config.fish`) and nothing changed.
+
+Cause: config.fish ends with a `return` guard. Any lines appended after it
+are never executed.
+
+Fix: create a dedicated conf.d file instead of appending to config.fish:
+
+    # ~/.config/fish/conf.d/mytool.fish
+    mytool init fish | source
+
+All existing integrations (starship, zoxide, direnv) already have conf.d/
+files. See Section 9, "Return Sentinel" for background.
+
+## Missing Dependencies
+
+Run `fish-deps` (defaults to `fish-deps status`) to see what is installed
+and what is missing. Common symptoms and their missing tools:
+
+    Symptom                                  Missing tool
+    ─────────────────────────────────────────────────────
+    ls output has no icons or colors         eza (or lsd)
+    cd does not remember directories         zoxide
+    cat shows no syntax highlighting         bat
+    fzf keybindings do nothing               fzf
+    Starship prompt not appearing            starship
+
+Install missing dependencies interactively:
+
+    fish-deps install
+
+Or install everything missing and update what is installed:
+
+    fish-deps sync
+
+See Section 6, "Dependency Catalog" for the full list grouped by tier
+(required, integrations, recommended).
+
+## Vi Mode Keybindings
+
+This config enables Vi mode by default (via C3 overrides), replacing the
+standard Emacs-style bindings. If Vi mode interferes with your workflow,
+override it in local.fish:
+
+    # in $__fish_user_dots_path/local.fish
+    fish_default_key_bindings
+
+This restores Emacs-style bindings without disabling the rest of C3
+(bang-bang, autopair, starship prompt, pager settings, etc.).
+
+To disable the entire C3 category (Vi mode and all other key/environment
+overrides):
+
+    set -U __fish_config_op_overrides off
+
+See Section 7, "C3 — Key and Environment Overrides" for the full list of
+what C3 controls.
+
+## Minimal Mode / Disabling Opinionated Features
+
+Disable all opinionated features at once:
+
+    set -U __fish_config_opinionated 0
+
+This turns off all six categories (aliases, auto-exec, overrides,
+integrations, logging, greeting) — leaving a clean shell with only PATH,
+XDG variables, and local.fish sourcing.
+
+Disable a single category:
+
+    set -U __fish_config_op_aliases off         # C1 — command shadows
+    set -U __fish_config_op_autoexec off        # C2 — startup side-effects
+    set -U __fish_config_op_overrides off       # C3 — key/env overrides
+    set -U __fish_config_op_integrations off    # C4 — terminal integrations
+    set -U __fish_config_op_logging off         # C5 — logging and capture
+    set -U __fish_config_op_greeting off        # C6 — greeting
+
+Keep one category active under a master disable:
+
+    set -U __fish_config_opinionated 0
+    set -U __fish_config_op_aliases 1           # only C1 stays on
+
+Re-enable everything:
+
+    set -Ue __fish_config_opinionated
+
+Or use the interactive TUI: `config-settings`.
+
+See Section 7, "Opinionated Components (Minimal Mode)" for the full
+component reference tables.
+
+---

docs/manual/12-viewing-this-manual.md

@@ -1,8 +1,8 @@
 ---
 title: Viewing This Manual
-manTitle: 11. VIEWING THIS MANUAL
+manTitle: 12. VIEWING THIS MANUAL
 sidebar:
-  order: 15
+  order: 16
 helpKeywords:
 - viewing
 - manual