From 00f70e855868ce1c402d1b4ca30d88ede8a6b7ee Mon Sep 17 00:00:00 2001 From: rootiest Date: Sun, 26 Jul 2026 04:02:57 -0400 Subject: [PATCH] docs(functions): merge remaining manual-only facts into headers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Word-level diff of every manual entry against its generated counterpart surfaced 546 tokens present in the manual and absent from the header — losses reconcile.py missed, because it compared description length and these headers are longer overall thanks to ARGUMENTS/RETURNS. Merged the substantive ones (546 -> 202 residual tokens, the remainder being synonym drift). Notable real fixes: - git-clean: -f/--force was missing from ARGUMENTS entirely - pkg: per-package-manager query table - qc: cli-role rationale, role paths, --role passthrough - config-help: site URL, xdg-open, man page path, case-insensitivity - agents-init: idempotency, .gitignore paths, upstream pull, wrapper callers - smart_exit: exit-builtin wiring note, $SCROLLBACK_HISTORY_DIR The manual's claim that claude/agy pass `agents-init --agents` is stale; both pass `--quiet` (full setup). Header wins, manual dropped. --- functions/agents-init.fish | 15 ++++++++++++--- functions/agy.fish | 4 +++- functions/auto-pull.fish | 7 ++++--- functions/bkg.fish | 3 ++- functions/cat.fish | 7 ++++--- functions/claude.fish | 4 +++- functions/config-help.fish | 13 ++++++++----- functions/config-settings.fish | 2 +- functions/detach.fish | 3 ++- functions/du.fish | 12 ++++++------ functions/gi.fish | 7 ++++--- functions/git-clean.fish | 9 +++++---- functions/limine-edit.fish | 3 ++- functions/open-url.fish | 5 ++++- functions/parur.fish | 1 + functions/pkg.fish | 8 ++++++++ functions/qc.fish | 17 +++++++++++------ functions/rm.fish | 2 +- functions/scrub.fish | 2 +- functions/search.fish | 2 +- functions/smart_exit.fish | 12 +++++++++--- functions/ssh.fish | 3 ++- functions/upgrade.fish | 2 +- functions/yt-dlp.fish | 3 ++- 24 files changed, 97 insertions(+), 49 deletions(-) diff --git a/functions/agents-init.fish b/functions/agents-init.fish index 9967991..c730954 100644 --- a/functions/agents-init.fish +++ b/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 diff --git a/functions/agy.fish b/functions/agy.fish index a904e74..a1f825b 100644 --- a/functions/agy.fish +++ b/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 diff --git a/functions/auto-pull.fish b/functions/auto-pull.fish index 9dd5e8d..1d52ffe 100644 --- a/functions/auto-pull.fish +++ b/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 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 diff --git a/functions/bkg.fish b/functions/bkg.fish index 87a5bfc..927db5b 100644 --- a/functions/bkg.fish +++ b/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 diff --git a/functions/cat.fish b/functions/cat.fish index 6ce0bae..76049a6 100644 --- a/functions/cat.fish +++ b/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 diff --git a/functions/claude.fish b/functions/claude.fish index 2395fcd..dad6ad4 100644 --- a/functions/claude.fish +++ b/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 diff --git a/functions/config-help.fish b/functions/config-help.fish index 8daf406..ecab1a7 100644 --- a/functions/config-help.fish +++ b/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 diff --git a/functions/config-settings.fish b/functions/config-settings.fish index b757437..2668897 100644 --- a/functions/config-settings.fish +++ b/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) diff --git a/functions/detach.fish b/functions/detach.fish index 4addcdf..d18c612 100644 --- a/functions/detach.fish +++ b/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 diff --git a/functions/du.fish b/functions/du.fish index 0e0693c..6fd4f93 100644 --- a/functions/du.fish +++ b/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 diff --git a/functions/gi.fish b/functions/gi.fish index fefe20a..e10d96f 100644 --- a/functions/gi.fish +++ b/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 diff --git a/functions/git-clean.fish b/functions/git-clean.fish index 98086eb..e43d60b 100644 --- a/functions/git-clean.fish +++ b/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 diff --git a/functions/limine-edit.fish b/functions/limine-edit.fish index 3cb98d3..f22a652 100644 --- a/functions/limine-edit.fish +++ b/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 diff --git a/functions/open-url.fish b/functions/open-url.fish index cb2969f..6c6496d 100644 --- a/functions/open-url.fish +++ b/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 diff --git a/functions/parur.fish b/functions/parur.fish index e8fc6ac..22bf1e2 100644 --- a/functions/parur.fish +++ b/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 diff --git a/functions/pkg.fish b/functions/pkg.fish index 87327dc..c11549c 100644 --- a/functions/pkg.fish +++ b/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 diff --git a/functions/qc.fish b/functions/qc.fish index 76137fd..55d0639 100644 --- a/functions/qc.fish +++ b/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 diff --git a/functions/rm.fish b/functions/rm.fish index cfac650..2e18c2c 100644 --- a/functions/rm.fish +++ b/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 # diff --git a/functions/scrub.fish b/functions/scrub.fish index 78dc95a..c528ab8 100644 --- a/functions/scrub.fish +++ b/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 # diff --git a/functions/search.fish b/functions/search.fish index ad72c8b..2494fb8 100644 --- a/functions/search.fish +++ b/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 diff --git a/functions/smart_exit.fish b/functions/smart_exit.fish index ab5a527..86118c9 100644 --- a/functions/smart_exit.fish +++ b/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 diff --git a/functions/ssh.fish b/functions/ssh.fish index 60ef6b4..4814277 100644 --- a/functions/ssh.fish +++ b/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 diff --git a/functions/upgrade.fish b/functions/upgrade.fish index 00cdd74..9c9974e 100644 --- a/functions/upgrade.fish +++ b/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 diff --git a/functions/yt-dlp.fish b/functions/yt-dlp.fish index 6af9714..3ce96fb 100644 --- a/functions/yt-dlp.fish +++ b/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