docs(functions): merge remaining manual prose into function headers

Folds the last seven manual entries whose description exceeded their header
back into the source-of-truth comment blocks: config-settings (Sponge/Paths
page detail, list-value parsing, width tiers, navigation keys), fish-deps
(install-method priority, dependency tiers), logs (fzf keybindings, ov
viewer behavior), kitty-logging (symlink wording, C5 inert-vs-uninstalled),
config-update (exec fish reload), yt-dlp (C1 guard). Drops duplicate example
lines left by the previous merge.

functions/config-settings.fish

@@ -11,17 +11,48 @@
 #   Opens an interactive full-screen TUI for managing fish config settings
 #   across four pages:
 #
-#     Universal — opinionated-category toggles, persistent (set -U / set -Ue)
+#     Universal — opinionated-category toggles (C1–C6) + master, persistent (set -U)
-#     Session   — opinionated-category toggles, this shell only (set -g / set -eg)
+#     Session   — the same toggles, current shell only (set -g)
-#     Sponge    — sponge history-scrubbing settings (delay, codes, secrets …)
+#     Sponge    — sponge history-scrubbing settings: delay, successful exit
-#     Paths     — scrollback log dir, log max, and user-dots path
+#                 codes, purge-only-on-exit, allow-previously-successful, and
+#                 extra sensitive variable-name tokens
+#     Paths     — scrollback log directory, scrollback max files, the user-dots
+#                 path, and the user-dots convenience symlink toggle (Dots link)
 #
-#   Toggle rows use ← / → (or h / l) to step OFF ← DEFAULT → ON.
+#   Toggle rows use ← / → (or h / l) to step OFF ← DEFAULT → ON; DEFAULT erases
-#   Value rows (Sponge, Paths) use Enter to edit inline; ← / h clears to default.
+#   the variable so the master switch / built-in default applies. Value rows
+#   (Sponge, Paths) use Enter to edit inline; ← / h clears to default. List rows
+#   (e.g. Extra secret, OK codes) accept values separated by commas and/or
+#   whitespace — "A, B", "A,B" and "A B" all yield the same two entries.
 #   Tab / Shift-Tab cycle forward / backward through pages.
 #   Changes apply immediately — no confirm step. Always available regardless of
 #   __fish_config_opinionated state.
 #
+#   The Sponge and Paths pages always write universal variables — these are
+#   persistent, set-and-forget settings with no per-session scope. Editing a
+#   scrollback row updates both the __fish_scrollback_history_* source-of-truth
+#   variables and the exported SCROLLBACK_HISTORY_* mirrors, so the AUR/tmux/
+#   zellij log wrappers (which read the exported names) see the change in the
+#   running session.
+#
+#   The panel adapts to the terminal width automatically, selecting from four
+#   layout tiers (with a 6-column buffer on each side before stepping up to the
+#   next tier) and horizontally centering the box. The panel redraws within
+#   ~0.3 s of a terminal resize with no keypress required.
+#
+#     COLUMNS >= 90  →  78-wide panel (most detail)
+#     COLUMNS >= 86  →  74-wide panel
+#     COLUMNS >= 82  →  70-wide panel
+#     COLUMNS  < 82  →  52-wide panel (default)
+#
+#   Navigation:
+#     ↑ ↓ / k j     Move cursor
+#     ← → / h l     Toggle rows: OFF ← DEFAULT → ON
+#     ←  / h        Value rows: clear to default
+#     Enter         Value rows: edit inline (Sponge / Paths pages)
+#     Tab / S-Tab   Next / previous page
+#     q / Escape    Exit
+#
 # ARGUMENTS
 #   -h, --help  Print usage and exit
 #

functions/config-update.fish

@@ -13,7 +13,7 @@
 #   The remote URL is hard-coded so the update works even if the local clone
 #   has no configured remote. Git output is suppressed; status is reported
 #   through colored messages. After a successful pull the function prints a
-#   short summary of changed files.
+#   short summary of changed files; run `exec fish` to reload the shell.
 #
 # ARGUMENTS
 #   -h, --help      Show this help message and exit

functions/edit.fish

@@ -41,8 +41,6 @@
 #   edit --terminal --new todo.md
 #   edit --editor=code --clipboard
 #   edit --text="hello world"
-#   edit ~/.config/fish/config.fish
-#   edit --visual notes.txt
 function edit --description 'Open files in a terminal or GUI editor with fallbacks'
     set -l c_head (set_color --bold cyan)
     set -l c_cmd (set_color --bold white)

functions/fish-deps.fish

@@ -8,8 +8,26 @@
 #   fish-deps [status|install|update|sync]
 #
 # DESCRIPTION
-#   Manages fish shell dependencies by dispatching to subcommand handlers.
+#   Unified command for managing all tools this configuration depends on,
-#   Defaults to status when no subcommand is given.
+#   dispatching to subcommand handlers. Defaults to status when no subcommand
+#   is given.
+#
+#   Install method priority (highest to lowest):
+#     1. git+cargo source build (fish shell itself)
+#     2. cargo (Rust tools — gets latest crate version)
+#     3. system PM (paru/apt/brew/etc.)
+#     4. git clone (fzf)
+#     5. curl installer (starship, fisher, uv)
+#
+#   When multiple methods are available you are prompted to choose.
+#
+#   Dependencies are grouped into three tiers:
+#
+#     Required      fish, fzf, zoxide
+#     Integrations  wakatime, tailscale
+#     Recommended   cargo, starship, uv, direnv, paru, yay, eza, lsd, bat,
+#                   btop, dust, duf, prettyping, ov, ripgrep, lazygit,
+#                   lazydocker, trash, kitty, wezterm, python3, yt-dlp
 #
 # ARGUMENTS
 #   status   Report installed/missing deps (default)

functions/kitty-logging.fish

@@ -8,17 +8,21 @@
 #   kitty-logging [install | uninstall | status | dismiss] [-h]
 #
 # DESCRIPTION
-#   Manages the fish-config Kitty scrollback watcher. `install` copies the
+#   Manages the fish-config Kitty scrollback watcher that powers C5 logging.
-#   canonical watcher into the Kitty config dir and wires it into kitty.conf via
+#   `install` symlinks the canonical watcher into the Kitty config dir (so it
-#   a sentinel-marked managed block (commenting out any conflicting active
+#   always tracks the source) and wires it into kitty.conf via a
-#   watcher line to avoid double-capture). `uninstall` reverses it. `status`
+#   sentinel-marked managed block, commenting out any conflicting active
-#   reports wiring, watcher version, and C5 logging state. `dismiss` silences the
+#   watcher line to avoid double-capture. `uninstall` reverses it. `status`
-#   per-session setup reminder. Runtime capture remains gated by the C5
+#   reports wiring, installed watcher version, and C5 logging state. `dismiss`
-#   .logging_disabled sentinel; install affects future Kitty instances only.
+#   silences the per-session setup reminder.
+#
+#   Runtime capture stays governed by the C5 .logging_disabled sentinel, so
+#   disabling __fish_config_op_logging makes the watcher inert without
+#   uninstalling. Install affects new Kitty windows only.
 #
 # ARGUMENTS
-#   install    Copy the watcher and add the managed block to kitty.conf
+#   install    Symlink the watcher and add the managed block to kitty.conf
-#   uninstall  Remove the managed block and the installed watcher
+#   uninstall  Remove the managed block and the watcher symlink
 #   status     Report wiring, watcher version, and C5 logging state
 #   dismiss    Stop the per-session reminder
 #   -h, --help Show this help

functions/logs.fish

@@ -11,6 +11,16 @@
 #   Interactively browses terminal log files (scrollback, paru, yay) sorted
 #   newest-first using fzf. Supports viewing in $PAGER, editing, and deletion.
 #
+#   Keybindings inside the fzf browser:
+#     Enter    Open in $PAGER
+#     Ctrl+E   Open in $EDITOR
+#     Ctrl+D   Delete (with confirmation)
+#     ?        Toggle keybind help overlay
+#
+#   Paru and yay logs open in ov with syntax highlighting and sticky section
+#   headers. Scrollback logs open in ov with per-command sticky prompt headers
+#   based on OSC 133 markers.
+#
 # ARGUMENTS
 #   -h, --help           Show help message
 #   -c, --category cat   Filter to one category: scrollback, paru, or yay

functions/repo-open.fish

@@ -42,9 +42,6 @@
 #   repo-open              # open current branch (+ subdir) in browser
 #   repo-open --print      # just print the URL
 #   repo-open --root       # repo home page for the current branch
-#   repo-open
-#   repo-open --print
-#   repo-open --root
 #
 # NOTES
 #   Typo abbreviation: open-repo (expands to repo-open on space/enter).

functions/yt-dlp.fish

@@ -15,6 +15,10 @@
 #   drops our --embed-thumbnail). All other arguments pass through
 #   untouched. --help and friends fall through to real yt-dlp.
 #
+#   Opinionated component (C1): when disabled via __fish_config_op_aliases
+#   (or the __fish_config_opinionated master), passes straight through to
+#   the system yt-dlp with no defaults injected.
+#
 # ARGUMENTS
 #   args...  Arguments forwarded to yt-dlp (defaults prepended)
 #   --no-embed-thumbnail  Skip thumbnail embedding for this run