functions/agents-init.fish

@@ -45,9 +45,18 @@
 #   version-managed from scripts/agents-tools/ and refreshed when their marker
 #   is stale.
 #
-#   With no flags, runs both --agents and --plugins setup. At the end of
-#   every invocation, commits any uncommitted changes in the AGENTS/ sub-repo
-#   so that agent-made edits are captured automatically.
+#   Downstream tooling can read AGENTS/.version directly — a changed MINOR
+#   field signals a structure change.
+#
+#   With no flags, runs both --agents and --plugins setup; --agents re-runs
+#   only the AGENTS.md / symlink step and --plugins only the plans/specs/
+#   devlogs wiring step. Managed paths are added to .gitignore. The sub-repo
+#   is pulled first when it has an upstream, and at the end of every
+#   invocation any uncommitted changes inside it are auto-committed so
+#   agent-made edits are captured automatically. Fully idempotent: a second
+#   run produces no output and no new commits.
+#
+#   Called automatically by the claude and agy wrappers on every invocation.
 #
 # ARGUMENTS
 #   -a, --agents   Set up AGENTS/ repo + AGENTS.md / CLAUDE.md symlinks only

functions/agy.fish

@@ -11,7 +11,9 @@
 #   Wrapper for the agy Antigravity AI CLI that ensures the AGENTS/
 #   sub-repository is initialized and any agent-made changes are committed
 #   before launch. Delegates all scaffold and commit logic to agents-init
-#   (full setup). All arguments are forwarded verbatim to the real agy binary.
+#   --quiet (full setup), which ensures AGENTS/ is scaffolded and CLAUDE.md
+#   is symlinked to AGENTS/AGENTS.md in the current project. All arguments
+#   are forwarded verbatim to the real agy binary.
 #
 #   Opinionated component (C1): when disabled via __fish_config_op_aliases
 #   (or the __fish_config_opinionated master), the command is passed through

functions/auto-pull.fish

@@ -15,8 +15,9 @@
 #   background fast-forwarded when you enter them (see conf.d/auto-pull.fish
 #   and _auto_pull_sync). The fish-config repo is always covered as a baseline
 #   and does not need to be added. The registry is a plain text file, one
-#   absolute git-toplevel path per line, stored machine-locally in
-#   ~/.config/.user-dots/fish/auto-pull.list (never committed to the config).
+#   absolute git-toplevel path per line, stored machine-locally at
+#   $__fish_user_dots_path/auto-pull.list (defaults to
+#   ~/.config/.user-dots/fish/auto-pull.list) and never committed.
 #
 #   Registry management works regardless of the C2 auto-execution guard; only
 #   the background sync itself is gated by __fish_config_op_autoexec.
@@ -25,7 +26,7 @@
 #   list               Show registered repos (default when no subcommand given)
 #   add [PATH]         Register PATH's git root; defaults to the current repo
 #   remove <NAME|PATH> Unregister by basename or exact path
-#   status             Show whether auto-pull is enabled and the registry path
+#   status             Show enabled/disabled state, repo count, and registry path
 #   -h, --help         Show this help message
 #
 # RETURNS

functions/bkg.fish

@@ -9,7 +9,8 @@
 #
 # DESCRIPTION
 #   Launches a command in the background, fully detached from the terminal
-#   using nohup. All stdout and stderr output is discarded.
+#   using nohup. All stdout and stderr output is discarded. Simpler than
+#   detach; no --version flag.
 #
 # ARGUMENTS
 #   command  The command to run detached

functions/cat.fish

@@ -8,9 +8,10 @@
 #   cat [args...]
 #
 # DESCRIPTION
-#   Enhanced cat replacement that uses bat for file display, runs ls when given
-#   a directory, falls back to raw cat for ANSI-colored log files, and finally
-#   falls back to standard cat if bat is not installed.
+#   Enhanced cat replacement. Wraps bat for files, giving syntax highlighting
+#   and line numbers; passes directories to ls; falls back to raw cat for
+#   ANSI-colored log files, and finally to /usr/bin/cat if bat is not
+#   installed.
 #
 # ARGUMENTS
 #   args...  Files or directories to display

functions/claude.fish

@@ -10,7 +10,9 @@
 # DESCRIPTION
 #   Wrapper for the claude CLI that ensures the AGENTS/ sub-repository is
 #   initialized and any agent-made changes are committed before launch.
-#   Delegates all scaffold and commit logic to agents-init (full setup).
+#   Delegates all scaffold and commit logic to agents-init --quiet (full
+#   setup), which ensures AGENTS/ is scaffolded and CLAUDE.md is symlinked
+#   to AGENTS/AGENTS.md in the current project.
 #   All arguments are forwarded verbatim to the real claude binary.
 #
 #   Opinionated component (C1): when disabled via __fish_config_op_aliases

functions/config-help.fish

@@ -17,11 +17,14 @@
 #   that matches the keyword. Lookup order: docs/fish-config.index (exact
 #   keyword aliases), then a normalized heading scan as fallback.
 #   When opened with ov a sticky navigation hint is shown at the top of the
-#   screen. Pass --html / -w to open the published documentation website in
-#   the default browser (deep links to a section aren't supported there —
-#   use the site's search box). Pass --man / -m to open the compiled man
-#   page; if a section keyword is given, the pager opens at the nearest
-#   match. Pass --help or -h for usage.
+#   screen. Section matching is case-insensitive. Pass --html / -w to open
+#   the published documentation website (https://fish-config-docs.pages.dev/)
+#   in the default browser via xdg-open — deep links to a section aren't
+#   supported there, so if a keyword is given a note points you to the site's
+#   search box instead. Pass --man / -m to open the compiled man page
+#   (docs/fish-config.1) via `man -l`; if a section keyword is given, the
+#   pager opens at the nearest match. Pass --help or -h for usage and the
+#   navigation key reference.
 #
 # ARGUMENTS
 #   section     Optional keyword to jump to a matching section heading

functions/config-settings.fish

@@ -9,7 +9,7 @@
 #
 # DESCRIPTION
 #   Opens an interactive full-screen TUI for managing fish config settings
-#   across four pages:
+#   across four pages, without having to type or remember variable names:
 #
 #     Universal — opinionated-category toggles (C1–C6) + master, persistent (set -U)
 #     Session   — the same toggles, current shell only (set -g)

functions/detach.fish

@@ -9,7 +9,8 @@
 #
 # DESCRIPTION
 #   Runs a command in the background using nohup, fully detached from the
-#   terminal with all output discarded.
+#   terminal with stdout/stderr discarded. The command survives the current
+#   session.
 #
 # ARGUMENTS
 #   -h, --help   Show help message

functions/du.fish

@@ -8,14 +8,14 @@
 #   du [--disk|--dir|--dua] [args...]
 #
 # DESCRIPTION
-#   Smart disk-usage wrapper that routes to duf (disk overview), dust (directory
-#   tree), or dua based on context or explicit flags. Falls back to system du
-#   when the preferred tool is not installed.
+#   Smart disk-usage dispatcher. Without flags, routes to the most appropriate
+#   tool by context; explicit flags force one. Falls back to system du when the
+#   preferred tool is not installed.
 #
 # ARGUMENTS
-#   --disk   Force duf for disk-level overview
-#   --dir    Force dust for directory-level breakdown
-#   --dua    Force dua interactive mode
+#   --disk   Force duf  (disk-level free/used overview)
+#   --dir    Force dust (per-directory tree breakdown)
+#   --dua    Force dua  (fast interactive space analyzer)
 #   args...  Files/directories or flags forwarded to the selected tool
 #
 # EXAMPLE

functions/gi.fish

@@ -9,8 +9,9 @@
 #
 # DESCRIPTION
 #   Generates .gitignore content by querying the gitignore.io API. Appends
-#   results to the repository's .gitignore with MD5-based deduplication, or
-#   prints to stdout with -s. Supports boilerplate and interactive prompt modes.
+#   results to the repository's .gitignore with MD5-based deduplication —
+#   patterns already present are not re-appended — or prints to stdout with
+#   -s. Supports generic boilerplate and interactive prompt modes.
 #
 # ARGUMENTS
 #   -h, --help         Show help message
@@ -19,7 +20,7 @@
 #   -b, --boilerplate  Append boilerplate from $GITIGNORE_BOILERPLATE
 #   -p, --prompt       Prompt for patterns to append
 #   -s, --stdout       Print API output to stdout instead of .gitignore
-#   targets            Comma-separated list of language/tool names
+#   targets            Comma- or space-separated list of language/tool names
 #
 # RETURNS
 #   0  Patterns appended or printed

functions/git-clean.fish

@@ -8,12 +8,13 @@
 #   git-clean [-h] [-f]
 #
 # DESCRIPTION
-#   Fetches and prunes the remote, updates the current branch, and deletes
-#   local branches whose tracking remote has been deleted. Automatically moves
-#   to main if currently on an orphaned branch.
+#   Fetches and prunes the remote, fast-forwards the current branch, and
+#   deletes local branches whose tracking remote has been deleted. Switches to
+#   main/master automatically if the current branch is orphaned.
 #
 # ARGUMENTS
-#   -h, --help   Show help message
+#   -h, --help    Show help message
+#   -f, --force   Force-delete unmerged branches too
 #   -f, --force  Force-delete unmerged orphaned branches (git branch -D)
 #
 # RETURNS

functions/limine-edit.fish

@@ -10,7 +10,8 @@
 # DESCRIPTION
 #   Opens /boot/limine.conf in sudoedit, then re-enrolls the config hash,
 #   runs CachyOS boot hooks (limine-mkinitcpio), and re-signs all Secure Boot
-#   files tracked by sbctl.
+#   files tracked by sbctl. Combines the edit and sign steps into a single
+#   command.
 #
 # EXAMPLE
 #   limine-edit

functions/open-url.fish

@@ -14,7 +14,8 @@
 #   binary rather than deferring to xdg-open, whose MIME dispatch can hand
 #   local text/html files to non-browser apps (e.g. ebook readers).
 #
-#   Silent by default: prints nothing on success (errors always go to stderr).
+#   Silent by default: prints nothing on success (errors always go to stderr);
+#   --silent / -s is accepted for explicitness.
 #
 #   Resolution order:
 #     1. $fish_help_browser  (explicit override)
@@ -38,6 +39,8 @@
 #   open-url -v https://fish-config-docs.pages.dev/
 #
 # NOTES
+#   Used internally by config-help --html.
+#
 #   Typo abbreviation: url-open (expands to open-url on space/enter).
 function open-url --description 'Open a URL in the best available web browser'
     argparse h/help s/silent v/verbose -- $argv

functions/parur.fish

@@ -10,6 +10,7 @@
 # DESCRIPTION
 #   Presents an fzf picker of all installed packages (via pacman -Qqs) with
 #   pacman -Qi previews, then removes the selected packages using paru or yay.
+#   Arch Linux only.
 #
 # RETURNS
 #   0  Packages removed or none selected

functions/pkg.fish

@@ -13,6 +13,14 @@
 #   In auto mode (no flag), detects whether each package is installed and
 #   toggles it — installing if absent, removing if present.
 #
+#   The package-installed check uses the correct query for each manager:
+#
+#     pacman/paru/yay  pacman -Qi
+#     apt              dpkg -s
+#     dnf/zypper/yum   rpm -q
+#     brew             brew list
+#     pkg              pkg info
+#
 # ARGUMENTS
 #   -h, --help       Show help message
 #   -i, --install    Force install mode

functions/qc.fish

@@ -8,12 +8,15 @@
 #   qc [prompt...]
 #
 # DESCRIPTION
-#   Quick-chat wrapper around aichat using the "cli" role. Resolves the
-#   aichat config directory (honoring $XDG_CONFIG_HOME), creates it if
-#   missing, and installs the bundled cli-agent role as a symlink at
-#   roles/cli.md on first use. Inherits aichat's own flags and tab
-#   completions (--wraps). The function is only defined when aichat is
-#   installed.
+#   Quick-chat wrapper around the aichat LLM CLI that defaults to the "cli"
+#   role — a system prompt tuned for concise, terminal-friendly output.
+#   Resolves the aichat config directory (honoring $XDG_CONFIG_HOME), creates
+#   it if missing, and on first use installs the bundled role by symlinking
+#   scripts/cli-agent.md to $XDG_CONFIG_HOME/aichat/roles/cli.md. Inherits
+#   every aichat flag and tab completion (--wraps aichat); passing --role/-r
+#   overrides the default role, so qc forwards to aichat unchanged. The
+#   function is only defined when aichat is installed. Run `qc --help` for
+#   aichat's full flag reference with the command name rewritten to qc.
 #
 # ARGUMENTS
 #   prompt...     Prompt forwarded to aichat
@@ -24,6 +27,8 @@
 #
 # EXAMPLE
 #   qc "how do I list open ports on linux?"
+#   qc -m ollama:llama3 "explain this error"
+#   qc --role coder "refactor this function"
 if type -q aichat
     function qc --wraps aichat --description 'Quick-chat wrapper around aichat (cli role)'
         if contains -- -h $argv; or contains -- --help $argv

functions/rm.fish

@@ -21,7 +21,7 @@
 # ARGUMENTS
 #   (none)              List current trash contents
 #   -e, --empty [opts]  Empty the trash; opts forwarded to trash empty
-#   -S, --secure        Permanently delete targets and run fstrim
+#   -S, --secure        Permanently delete targets and run fstrim (irreversible)
 #   -r, -R, --recursive Forwarded to trash put alongside path arguments
 #   args...             Files or paths to trash or remove
 #

functions/scrub.fish

@@ -15,7 +15,7 @@
 #   IDE directories, and AI tool artifacts.
 #
 # ARGUMENTS
-#   -a, --aggressive  Also purge node_modules, *.log, .idea, AI artifacts
+#   -a, --aggressive  Also purge node_modules, *.log, .cache, .idea, AI artifacts
 #   -d, --dry-run     Show targets without deleting
 #   -h, --help        Show usage help
 #

functions/search.fish

@@ -9,7 +9,7 @@
 #
 # DESCRIPTION
 #   Delegates to paru or yay for interactive AUR package search and
-#   installation. Falls back to yay if paru is not installed.
+#   installation. Falls back to yay if paru is not installed. Arch Linux only.
 #
 # ARGUMENTS
 #   args...  Arguments forwarded to paru or yay

functions/smart_exit.fish

@@ -8,9 +8,10 @@
 #   smart_exit [-h] [-n]
 #
 # DESCRIPTION
-#   Closes the shell session, capturing and archiving the terminal scrollback
-#   log before exit (Kitty only). Automatically prunes junk and excess log
-#   files according to $SCROLLBACK_HISTORY_MAX_FILES.
+#   Closes the shell session. In Kitty, captures the terminal scrollback to a
+#   timestamped log file in $SCROLLBACK_HISTORY_DIR before exiting.
+#   Automatically prunes junk and the oldest logs when the count exceeds
+#   $SCROLLBACK_HISTORY_MAX_FILES.
 #
 # ARGUMENTS
 #   -h, --help    Show help message
@@ -21,7 +22,12 @@
 #   1  Argument parsing failed
 #
 # EXAMPLE
+#   smart_exit
 #   smart_exit --no-log
+#
+# NOTES
+#   The exit builtin is wired to smart_exit for interactive sessions. Typing
+#   `exit` or Ctrl+D behaves identically to calling smart_exit directly.
 function smart_exit --description 'Capture colorized scrollback before exiting, with pruning and safe overrides'
     # Opinionated guard (C3): exit plainly when overrides are disabled.
     # This composes with Task #4's __fish_config_enable_logging, which will

functions/ssh.fish

@@ -9,7 +9,8 @@
 #
 # DESCRIPTION
 #   Wraps ssh with kitten ssh inside Kitty terminal for better terminal
-#   integration (e.g. terminfo forwarding). Falls back to system ssh on
+#   integration (terminfo forwarding, multiplexing, copy/paste support).
+#   Falls back to system ssh on
 #   other terminals.
 #
 # ARGUMENTS

functions/upgrade.fish

@@ -9,7 +9,7 @@
 #
 # DESCRIPTION
 #   Runs a full system upgrade via paru or yay with --noconfirm. Falls
-#   back to yay if paru is not installed.
+#   back to yay if paru is not installed. Arch Linux only.
 #
 # RETURNS
 #   0  Upgrade completed successfully

functions/yt-dlp.fish

@@ -12,7 +12,8 @@
 #   (--sponsorblock-remove all, --embed-subs, --embed-metadata,
 #   --embed-thumbnail). Each default is suppressed if the user already
 #   passes that flag, its alias, or its negation (e.g. --no-embed-thumbnail
-#   drops our --embed-thumbnail). All other arguments pass through
+#   drops our --embed-thumbnail; --no-sponsorblock or your own
+#   --sponsorblock-remove drops ours). 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