docs(functions): split RETURNS into EXIT STATUS and stdout RETURNS

RETURNS previously conflated fish's $status exit code with genuine
stdout/printed output, e.g. rm listing "0/1" as if they were print
values rather than exit codes. Rename RETURNS to EXIT STATUS across
all 83 documented functions, and reintroduce RETURNS as a distinct
label reserved for the 15 functions that actually print to stdout.

Update build-manual.py's ENTRY_HEADS to render Exit Status before
Returns, manualtools.py's SECTIONS constant, and AGENTS.md's label
order and label-usage guidance to match. Add two verify-manual.py
regression tests: EXIT STATUS bodies must never contain stray
stdout/printed language, and Returns: must always render after
Exit Status: when both are present. Regenerate docs/fish-config.md.

docs/build-manual.py

@@ -416,7 +416,12 @@ def prettify(body: str, entry_name: str | None = None) -> str:
     return "\n".join(out)
 
 
-ENTRY_HEADS = {"ARGUMENTS": "Arguments:", "RETURNS": "Returns:", "NOTES": "Notes:"}
+ENTRY_HEADS = {
+    "ARGUMENTS": "Arguments:",
+    "EXIT STATUS": "Exit Status:",
+    "RETURNS": "Returns:",
+    "NOTES": "Notes:",
+}
 
 
 def render_entry(fn: dict[str, list[str]], used_by: list[str], link=None) -> str:

docs/fish-config.md

@@ -708,7 +708,7 @@ Add -i (interactive confirmation) to destructive commands:
       -s, --silent  Suppress directory creation output
       <dir>         Directory to create and enter
 
-    Returns:
+    Exit Status:
       0  Directory created (or already existed) and entered successfully
       1  Directory creation or cd failed
 
@@ -741,7 +741,7 @@ Add -i (interactive confirmation) to destructive commands:
     Arguments:
       file  One or more file paths to create
 
-    Returns:
+    Exit Status:
       0  Files created
       1  No file argument provided
 
@@ -785,7 +785,7 @@ Add -i (interactive confirmation) to destructive commands:
       -r, -R, --recursive Forwarded to trash put alongside path arguments
       args...             Files or paths to trash or remove
 
-    Returns:
+    Exit Status:
       0  Operation succeeded
       1  trash put failed or file not found
 
@@ -812,7 +812,7 @@ Add -i (interactive confirmation) to destructive commands:
       -d, --dry-run     Show targets without deleting
       -h, --help        Show usage help
 
-    Returns:
+    Exit Status:
       0  Sweep completed (or dry run shown)
       1  fd not found, or unknown argument provided
 
@@ -846,7 +846,7 @@ Add -i (interactive confirmation) to destructive commands:
     Arguments:
       args...  Arguments forwarded to clone-in-kitty (typically a repo URL)
 
-    Returns:
+    Exit Status:
       0  Repository cloned
       1  Not running inside Kitty terminal
 
@@ -863,7 +863,7 @@ Add -i (interactive confirmation) to destructive commands:
     Arguments:
       args...  Arguments forwarded to clone-in-kitty (typically a repo URL)
 
-    Returns:
+    Exit Status:
       0  Repository cloned
       1  Not running inside Kitty terminal
 
@@ -899,7 +899,7 @@ Add -i (interactive confirmation) to destructive commands:
       -s, --silent      Suppress all output, including the editor's
       -h, --help        Show this help message
 
-    Returns:
+    Exit Status:
       0  Editor launched successfully
       1  Conflicting flags, no editor found, or clipboard read failed
 
@@ -922,7 +922,7 @@ Add -i (interactive confirmation) to destructive commands:
     Arguments:
       command_prefix   Search history for the newest command matching this
 
-    Returns:
+    Exit Status:
       The edited command's exit status, or a message when history lookup
       found nothing.
 
@@ -996,7 +996,7 @@ Add -i (interactive confirmation) to destructive commands:
       status             Show enabled/disabled state, repo count, and registry path
       -h, --help         Show this help message
 
-    Returns:
+    Exit Status:
       0  Subcommand succeeded
       1  Bad usage, target is not a git repo, or target not registered
 
@@ -1016,7 +1016,7 @@ Add -i (interactive confirmation) to destructive commands:
     Arguments:
       branch_name   Branch to switch to or create
 
-    Returns:
+    Exit Status:
       0  Branch checked out or created
       1  Not inside a git work tree
 
@@ -1041,10 +1041,14 @@ Add -i (interactive confirmation) to destructive commands:
       -s, --stdout       Print API output to stdout instead of .gitignore
       targets            Comma- or space-separated list of language/tool names
 
-    Returns:
-      0  Patterns appended or printed
+    Exit Status:
+      0  Patterns appended, or resolved with -s/--stdout or -l/--list
       1  Not in a git repository or API fetch failed
 
+    Returns:
+      With -s/--stdout, the fetched .gitignore pattern text, printed to stdout.
+      With -l/--list, the supported target list, printed to stdout.
+
     Example:
     gi python,venv
     gi -b -p
@@ -1062,7 +1066,7 @@ Add -i (interactive confirmation) to destructive commands:
       -h, --help   Show help message
       -f, --force  Force-delete unmerged orphaned branches (git branch -D)
 
-    Returns:
+    Exit Status:
       0  Cleanup complete
       1  Argument parsing failed
 
@@ -1093,7 +1097,7 @@ Add -i (interactive confirmation) to destructive commands:
     Arguments:
       args...   Forwarded verbatim to git fetch
 
-    Returns:
+    Exit Status:
       0  Fetch and status succeeded
       1  Not inside a git work tree
 
@@ -1131,7 +1135,7 @@ Add -i (interactive confirmation) to destructive commands:
     pacman -Qi previews, then removes the selected packages using paru or yay.
     Arch Linux only.
 
-    Returns:
+    Exit Status:
       0  Packages removed or none selected
       1  No AUR helper (paru or yay) found
 
@@ -1161,7 +1165,7 @@ Add -i (interactive confirmation) to destructive commands:
       -u, --uninstall  Force uninstall mode
       package          One or more package names to install or remove
 
-    Returns:
+    Exit Status:
       0  Operation completed
       1  No supported package manager found, unknown flag, or package operation failed
 
@@ -1180,7 +1184,7 @@ Add -i (interactive confirmation) to destructive commands:
     Arguments:
       args...  Arguments forwarded to paru or yay
 
-    Returns:
+    Exit Status:
       0  AUR helper ran successfully
       1  No AUR helper (paru or yay) found
 
@@ -1194,7 +1198,7 @@ Add -i (interactive confirmation) to destructive commands:
     Runs a full system upgrade via paru or yay with --noconfirm. Falls
     back to yay if paru is not installed. Arch Linux only.
 
-    Returns:
+    Exit Status:
       0  Upgrade completed successfully
       1  No AUR helper (paru or yay) found
 
@@ -1244,7 +1248,7 @@ Add -i (interactive confirmation) to destructive commands:
       update   Update all installed deps
       sync     Install missing deps, then update all
 
-    Returns:
+    Exit Status:
       0  Subcommand completed
       1  Unknown subcommand
 
@@ -1309,7 +1313,7 @@ Add -i (interactive confirmation) to destructive commands:
     Arguments:
       --brief  Suppress per-file output; show only the final summary
 
-    Returns:
+    Exit Status:
       0  All binaries verified (or summary shown)
       1  sbctl is not installed
 
@@ -1336,7 +1340,7 @@ Add -i (interactive confirmation) to destructive commands:
     otherwise require a password entry. Clears the sudo credential cache
     when re-enabling, so the lockdown takes effect immediately.
 
-    Returns:
+    Exit Status:
       0  Rule toggled
 
     Example:
@@ -1380,7 +1384,7 @@ Add -i (interactive confirmation) to destructive commands:
       command  The command to run detached
       args...  Additional arguments for the command
 
-    Returns:
+    Exit Status:
       0  Command launched successfully
       1  No command provided
 
@@ -1401,7 +1405,7 @@ Add -i (interactive confirmation) to destructive commands:
       command      The command to run detached
       args...      Additional arguments for the command
 
-    Returns:
+    Exit Status:
       0  Command launched or help/version shown
       1  No command provided or unknown option
 
@@ -1422,7 +1426,7 @@ Add -i (interactive confirmation) to destructive commands:
       command...        Command to run in the new pane; opens a bare fish
                         shell if omitted
 
-    Returns:
+    Exit Status:
       0  Pane opened successfully
       1  Not running inside Kitty or WezTerm
 
@@ -1440,7 +1444,7 @@ Add -i (interactive confirmation) to destructive commands:
     Arguments:
       args...  Arguments forwarded to the spawn command
 
-    Returns:
+    Exit Status:
       0  Window opened successfully
       1  Not running inside Kitty or WezTerm
 
@@ -1473,7 +1477,7 @@ Add -i (interactive confirmation) to destructive commands:
     Arguments:
       args...  Arguments forwarded to the terminal's launch command
 
-    Returns:
+    Exit Status:
       0  Tab opened successfully
       1  No supported terminal found
 
@@ -1493,10 +1497,13 @@ Add -i (interactive confirmation) to destructive commands:
       -h, --help  Show usage help
       args...     Arguments forwarded to the clipboard tool
 
-    Returns:
-      0  Clipboard contents printed successfully
+    Exit Status:
+      0  Clipboard contents read successfully
       1  No supported clipboard tool found
 
+    Returns:
+      The clipboard contents, printed to stdout
+
     Example:
     p | grep foo
     p > file.txt
@@ -1511,10 +1518,13 @@ Add -i (interactive confirmation) to destructive commands:
     Arguments:
       args...  Arguments forwarded to the clipboard tool
 
-    Returns:
-      0  Clipboard contents printed successfully
+    Exit Status:
+      0  Clipboard contents read successfully
       1  No supported clipboard tool found
 
+    Returns:
+      The clipboard contents, printed to stdout
+
     Example:
     paste > file.txt
 
@@ -1528,7 +1538,7 @@ Add -i (interactive confirmation) to destructive commands:
     Arguments:
       text  Text to copy; reads from stdin if omitted
 
-    Returns:
+    Exit Status:
       0  Text copied to clipboard
       1  No clipboard provider found
 
@@ -1565,10 +1575,13 @@ Add -i (interactive confirmation) to destructive commands:
     Fetches and prints the machine's public IPv6 address using icanhazip.com.
     Prints an error message if IPv6 is unavailable on the current network.
 
-    Returns:
-      0  IPv6 address printed
+    Exit Status:
+      0  IPv6 address resolved
       1  IPv6 unavailable or not supported on this network
 
+    Returns:
+      The machine's public IPv6 address, printed to stdout
+
     Example:
     gip6
 
@@ -1626,7 +1639,7 @@ Add -i (interactive confirmation) to destructive commands:
       -h, --help           Show help message
       -c, --category cat   Filter to one category: scrollback, paru, or yay
 
-    Returns:
+    Exit Status:
       0  File viewed or no file selected
       1  No log files found
 
@@ -1648,7 +1661,7 @@ Add -i (interactive confirmation) to destructive commands:
       -h, --help    Show help message
       -n, --no-log  Exit without saving a scrollback log
 
-    Returns:
+    Exit Status:
       0  Shell session exited
       1  Argument parsing failed
 
@@ -1724,7 +1737,7 @@ Add -i (interactive confirmation) to destructive commands:
       -s, --silent   Suppress all output; errors only (standard UNIX convention)
       -h, --help     Show this help message and exit
 
-    Returns:
+    Exit Status:
       0  Setup completed successfully
       1  Fatal error (git init failed, move failed, etc.)
 
@@ -1754,7 +1767,7 @@ Add -i (interactive confirmation) to destructive commands:
     Arguments:
       ARGS  Any arguments forwarded verbatim to the underlying agy binary
 
-    Returns:
+    Exit Status:
       Exit status of the underlying agy binary
 
     Example:
@@ -1795,7 +1808,7 @@ Add -i (interactive confirmation) to destructive commands:
     Arguments:
       ARGS  Any arguments forwarded verbatim to the underlying claude binary
 
-    Returns:
+    Exit Status:
       Exit status of the underlying claude binary
 
     Example:
@@ -1860,7 +1873,7 @@ Add -i (interactive confirmation) to destructive commands:
       prompt...     Prompt forwarded to aichat
       -h, --help    Show usage help
 
-    Returns:
+    Exit Status:
       aichat's exit status.
 
     Example:
@@ -1882,7 +1895,7 @@ Add -i (interactive confirmation) to destructive commands:
       -g, --global  Apply at user/global scope instead of workspace/project
       -h, --help    Show usage help
 
-    Returns:
+    Exit Status:
       0  Mode applied successfully
       1  No on/off mode specified
 
@@ -1907,7 +1920,7 @@ Add -i (interactive confirmation) to destructive commands:
       -s, --speed N       Encoder speed 0-10 (default: 3, 0 = slowest)
       -h, --help          Show help message
 
-    Returns:
+    Exit Status:
       0  Conversion complete
       1  File not found, missing dependency, or encode step failed
 
@@ -1995,7 +2008,7 @@ Add -i (interactive confirmation) to destructive commands:
     Arguments:
       owner/repo  The repository path in owner/name format
 
-    Returns:
+    Exit Status:
       0  Issues linked and synced (or no unlinked issues found)
       1  Missing required argument or environment variables
 
@@ -2059,10 +2072,14 @@ Add -i (interactive confirmation) to destructive commands:
       -m, --man   Open the compiled man page via man -l
       -h, --help  Print usage and navigation reference, then exit
 
-    Returns:
-      0  Manual displayed (or --help printed)
+    Exit Status:
+      0  Manual displayed
       1  Documentation file not found, or required tool not available
 
+    Returns:
+      With -h/--help, the usage and navigation reference, printed to stdout.
+      Otherwise, the manual is shown via the resolved pager (not captured stdout).
+
     Notes:
       The preferred invocation is `help config [...]` — this function is
       registered as a handler in the help wrapper so that syntax works
@@ -2131,7 +2148,7 @@ Add -i (interactive confirmation) to destructive commands:
     Arguments:
       -h, --help  Print usage and exit
 
-    Returns:
+    Exit Status:
       0  Exited normally (q or Escape pressed)
       1  Unknown flag passed
 
@@ -2150,7 +2167,7 @@ Add -i (interactive confirmation) to destructive commands:
     Arguments:
       args  Passed through verbatim to config-settings
 
-    Returns:
+    Exit Status:
       Same as config-settings
 
     Example:
@@ -2172,7 +2189,7 @@ Add -i (interactive confirmation) to destructive commands:
       -f, --force     Stash local changes before pulling, then pop the stash
       -n, --dry-run   Check for upstream changes without applying them
 
-    Returns:
+    Exit Status:
       0  Config updated (or already up to date)
       1  Update failed (network error, merge conflict, or not a git repo)
 
@@ -2192,7 +2209,7 @@ Add -i (interactive confirmation) to destructive commands:
       -h, --help   Show help message
       directory    Path to the compose project (defaults to current directory)
 
-    Returns:
+    Exit Status:
       0  Services updated and running
       1  Directory not found or no docker-compose.yml present
 
@@ -2222,7 +2239,7 @@ Add -i (interactive confirmation) to destructive commands:
     Arguments:
       args...  Arguments forwarded to the joplin command
 
-    Returns:
+    Exit Status:
       0  Joplin ran successfully
       1  joplin binary not found in PATH
 
@@ -2252,7 +2269,7 @@ Add -i (interactive confirmation) to destructive commands:
       dismiss    Stop the per-session reminder
       -h, --help Show this help
 
-    Returns:
+    Exit Status:
       0  Success
       1  Unknown subcommand/flag, kitty missing, or a write failure
 
@@ -2296,7 +2313,7 @@ Add -i (interactive confirmation) to destructive commands:
       -v, --verbose  Print which browser is being launched
       -h, --help     Print usage and exit
 
-    Returns:
+    Exit Status:
       0  Browser launched
       1  No URL given, invalid $BROWSER, or no browser found
 
@@ -2320,7 +2337,7 @@ Add -i (interactive confirmation) to destructive commands:
     Arguments:
       commands  Bash command string to execute and replay
 
-    Returns:
+    Exit Status:
       0  Commands ran successfully and changes were replayed
       1  Bash command exited with a non-zero status
 
@@ -2358,10 +2375,13 @@ Add -i (interactive confirmation) to destructive commands:
       -r, --root   Ignore the current sub-directory; link to the repo root
       -h, --help   Print usage and exit
 
-    Returns:
-      0  URL opened (or printed)
+    Exit Status:
+      0  URL opened, or resolved with -p/--print
       1  Not a git repo, no origin remote, or browser launch failed
 
+    Returns:
+      With -p/--print, the resolved repository URL, printed to stdout
+
     Notes:
       Typo abbreviation: open-repo (expands to repo-open on space/enter).
 
@@ -2393,7 +2413,7 @@ Add -i (interactive confirmation) to destructive commands:
       command  Command to run with sleep inhibition active
       args...  Arguments forwarded to the command
 
-    Returns:
+    Exit Status:
       0  Command ran and completed
       1  No command provided
 

docs/manualtools.py

@@ -66,6 +66,7 @@ SECTIONS = (
     "SYNOPSIS",
     "DESCRIPTION",
     "ARGUMENTS",
+    "EXIT STATUS",
     "RETURNS",
     "EXAMPLE",
     "NOTES",

docs/verify-manual.py

@@ -572,6 +572,43 @@ def test_sidebar_has_no_duplicate_functions_entry():
     assert len(labels) == 15, f"expected Overview + 14 categories, got {len(labels)}"
 
 
+def test_exit_status_never_describes_stdout_content():
+    """EXIT STATUS documents $status; stdout/printed content belongs in RETURNS.
+
+    Regression guard for the RETURNS -> EXIT STATUS split: a row like
+    "0  Patterns appended, or the requested content printed" re-introduces
+    the exact ambiguity (exit code vs. printed output) the split exists to
+    remove. A `--stdout`-style flag name is not itself an offense — only
+    "stdout" used as a bare word (not part of a flag) counts.
+    """
+    offenders = []
+    for name, fn in _parsed_functions().items():
+        for line in fn.get("EXIT STATUS", []):
+            if re.search(r"(?<!-)\bstdout\b|\bprinted\b", line, re.IGNORECASE):
+                offenders.append(f"{name}: {line.strip()}")
+    assert not offenders, "stdout/printed language leaked into EXIT STATUS:\n  " + "\n  ".join(
+        offenders
+    )
+
+
+def test_returns_renders_after_exit_status():
+    """When a function has both, Exit Status: must render before Returns:."""
+    import build_manual
+
+    fn = {
+        "SYNOPSIS": ["thing"],
+        "DESCRIPTION": ["Does a thing."],
+        "EXIT STATUS": ["0  Always"],
+        "RETURNS": ["The thing, printed to stdout"],
+        "EXAMPLE": ["thing"],
+    }
+    out = build_manual.render_entry(fn, [])
+    exit_pos = out.find("Exit Status:")
+    returns_pos = out.find("Returns:")
+    assert exit_pos != -1 and returns_pos != -1, f"missing a section head:\n{out}"
+    assert exit_pos < returns_pos, f"Returns: rendered before Exit Status::\n{out}"
+
+
 def test_site_avoids_reserved_dir():
     """No output directory may collide with a Cloudflare Pages reserved name.
 

functions/__config_settings_apply.fish

@@ -19,7 +19,7 @@
 #   scope    "universal" or "session"
 #   value    "on", "off", "DEFAULT", or any arbitrary string (universal scope only)
 #
-# RETURNS
+# EXIT STATUS
 #   0  Always
 #
 # EXAMPLE

functions/__config_settings_draw.fish

@@ -24,7 +24,7 @@
 #   cur_scope  "universal" or "session"
 #   var1–var7  Variable names for rows 0–6 (6 categories + master)
 #
-# RETURNS
+# EXIT STATUS
 #   0  Always
 #
 # EXAMPLE

functions/__config_settings_draw_value.fish

@@ -20,7 +20,7 @@
 #   cur_row  0-based highlighted row within the page
 #   page     "sponge" or "paths"
 #
-# RETURNS
+# EXIT STATUS
 #   0  Always
 #
 # EXAMPLE

functions/__config_settings_get_raw.fish

@@ -12,8 +12,11 @@
 # ARGUMENTS
 #   varname  Variable name without the $ prefix
 #
+# EXIT STATUS
+#   0  Always
+#
 # RETURNS
-#   0  Always; prints the value or "DEFAULT" to stdout
+#   The value, or "DEFAULT" if unset, printed to stdout
 #
 # EXAMPLE
 #   set v (__config_settings_get_raw sponge_delay)   # "2" or "DEFAULT"

functions/__config_settings_get_val.fish

@@ -14,8 +14,11 @@
 #   varname  Variable name without $ prefix
 #   scope    "universal" or "session"
 #
+# EXIT STATUS
+#   0  Always
+#
 # RETURNS
-#   0  Always; prints "on", "off", or "DEFAULT" to stdout
+#   "on", "off", or "DEFAULT", printed to stdout
 #
 # EXAMPLE
 #   set result (__config_settings_get_val __fish_config_op_aliases universal)

functions/__config_settings_pagetab.fish

@@ -15,8 +15,11 @@
 #   active_idx  0–3, the active page index
 #   iw          inner width in columns to pad the strip to
 #
+# EXIT STATUS
+#   0  Always
+#
 # RETURNS
-#   0  Always; prints the tab strip (no trailing newline beyond printf's)
+#   The rendered tab strip, printed to stdout (no trailing newline beyond printf's)
 #
 # EXAMPLE
 #   set strip (__config_settings_pagetab 2 76)

functions/__config_settings_read_key.fish

@@ -21,15 +21,18 @@
 # ARGUMENTS
 #   (none)
 #
-# RETURNS
-#   0  A key was read; one of these tokens is printed to stdout:
-#        up down left right   arrow keys
-#        space tab backtab enter escape backspace
-#        quit                 Ctrl-C (byte 3) in raw mode
-#        <char>               any other single printable character
-#        ""                   nothing decodable was read
+# EXIT STATUS
+#   0  A key was read
 #   1  The terminal could not be put into raw mode (stdin is not a TTY)
 #
+# RETURNS
+#   One token, printed to stdout:
+#     up down left right   arrow keys
+#     space tab backtab enter escape backspace
+#     quit                 Ctrl-C (byte 3) in raw mode
+#     <char>               any other single printable character
+#     ""                   nothing decodable was read
+#
 # EXAMPLE
 #   set -l key (__config_settings_read_key)
 #   or return                       # not a TTY — bail

functions/__config_settings_set_value.fish

@@ -17,7 +17,7 @@
 #   type     "list" (whitespace-split) or any other tag (single value)
 #   value    The new value; empty string erases (reset to default)
 #
-# RETURNS
+# EXIT STATUS
 #   0  Always
 #
 # EXAMPLE

functions/__fish_config_op_enabled.fish

@@ -23,7 +23,7 @@
 #                      __fish_config_op_logging, or
 #                      __fish_config_op_greeting
 #
-# RETURNS
+# EXIT STATUS
 #   0  Component enabled (category explicitly truthy; or category unset and master not falsy)
 #   1  Component disabled (category explicitly falsy; or category unset and master falsy; or no argument with falsy master)
 #

functions/__fish_config_sync_logging.fish

@@ -14,7 +14,7 @@
 #   Safe to call at any time; wrapper removal only affects files bearing
 #   the generated version-marker comment.
 #
-# RETURNS
+# EXIT STATUS
 #   0  Always
 #
 # EXAMPLE

functions/__fish_real_command.fish

@@ -18,9 +18,12 @@
 # ARGUMENTS
 #   name  Command name to resolve (e.g. paru, yay)
 #
+# EXIT STATUS
+#   0  A non-wrapper binary was found
+#   1  No non-wrapper binary found on PATH
+#
 # RETURNS
-#   0  Real binary path printed to stdout
-#   1  No non-wrapper binary found on PATH (nothing printed)
+#   The resolved binary's real path, printed to stdout (nothing on failure)
 #
 # EXAMPLE
 #   set -l real (__fish_real_command paru)   # -> /usr/bin/paru, not the shim

functions/__fish_user_dots_link.fish

@@ -23,7 +23,7 @@
 # ARGUMENTS
 #   (none)
 #
-# RETURNS
+# EXIT STATUS
 #   0  Always
 #
 # EXAMPLE

functions/__fish_variable_check.fish

@@ -12,7 +12,7 @@
 # ARGUMENTS
 #   variable_name  Name of the variable to check (without $ prefix)
 #
-# RETURNS
+# EXIT STATUS
 #   0  True (opt-in): value matches 1, true, yes, on, or y
 #   1  False (opt-out): value matches 0, false, no, off, or n
 #   2  Empty: variable is unset or empty

functions/__fzf_inline_picker.fish

@@ -9,7 +9,7 @@
 #   into the command line at the cursor position. Bound to @@ by default.
 #   Repaints the prompt after selection or cancellation.
 #
-# RETURNS
+# EXIT STATUS
 #   0  Always; no-op if fzf is cancelled
 #
 # EXAMPLE

functions/__kitty_logging_dir.fish

@@ -9,8 +9,11 @@
 #   order: $KITTY_CONFIG_DIRECTORY, else $XDG_CONFIG_HOME/kitty, else
 #   ~/.config/kitty.
 #
+# EXIT STATUS
+#   0  Always
+#
 # RETURNS
-#   0  Always (path printed to stdout)
+#   The Kitty configuration directory path, printed to stdout
 #
 # EXAMPLE
 #   set -l dir (__kitty_logging_dir)

functions/__kitty_logging_has_watcher.fish

@@ -9,7 +9,7 @@
 #   (non-commented) `watcher` directive — whether the fish-config managed one or
 #   a user's own. Used to suppress the setup reminder and to inform status.
 #
-# RETURNS
+# EXIT STATUS
 #   0  An active watcher directive is present
 #   1  None present, or kitty.conf does not exist
 #

functions/__kitty_logging_version.fish

@@ -11,8 +11,11 @@
 # ARGUMENTS
 #   file  Path to a watcher script
 #
+# EXIT STATUS
+#   0  Always
+#
 # RETURNS
-#   0  Always (integer printed to stdout)
+#   The watcher version as an integer (0 if absent), printed to stdout
 #
 # EXAMPLE
 #   __kitty_logging_version ~/.config/kitty/fish-config-watcher.py

functions/_agents_init_ensure_gitignore.fish

@@ -24,7 +24,7 @@
 #   label     Short description used in the block comment header
 #   pattern   One or more gitignore patterns to ensure are present
 #
-# RETURNS
+# EXIT STATUS
 #   0  All patterns already ignored or successfully appended
 #   1  Could not write to .gitignore
 #

functions/_agents_init_install_tools.fish

@@ -15,7 +15,7 @@
 # ARGUMENTS
 #   agents_dir  Absolute path to the AGENTS/ sub-repo root
 #
-# RETURNS
+# EXIT STATUS
 #   0  Tooling is current or was installed/updated successfully
 #   1  Canonical source missing or a copy failed
 #

functions/_auto_pull_sync.fish

@@ -19,7 +19,7 @@
 # ARGUMENTS
 #   dir  Absolute path to the git repository to fast-forward
 #
-# RETURNS
+# EXIT STATUS
 #   0  Fast-forward applied (or already up to date)
 #   1  A precondition failed; nothing was changed
 #

functions/_fish_deps_catalog.fish

@@ -49,9 +49,12 @@ end
 # ARGUMENTS
 #   bin  The binary name to look up in the catalog
 #
+# EXIT STATUS
+#   0  Binary found in the catalog
+#   1  Binary not found
+#
 # RETURNS
-#   0  Index printed to stdout
-#   1  Binary not found (empty output)
+#   The binary's 1-based catalog index, printed to stdout (nothing on failure)
 #
 # EXAMPLE
 #   _fish_deps_catalog_idx fzf

functions/_fish_deps_pm_install.fish

@@ -12,7 +12,7 @@
 # ARGUMENTS
 #   pkg  The package name to install
 #
-# RETURNS
+# EXIT STATUS
 #   0  Package installed successfully
 #   1  No supported package manager found
 #

functions/_fish_deps_pm_upgrade.fish

@@ -12,7 +12,7 @@
 # ARGUMENTS
 #   pkg  The package name to upgrade
 #
-# RETURNS
+# EXIT STATUS
 #   0  Package upgraded successfully
 #   1  No supported package manager found
 #

functions/_fish_mkdir_p.fish

@@ -14,7 +14,7 @@
 #   -s, --silent  Suppress all output
 #   dir           The directory path to create
 #
-# RETURNS
+# EXIT STATUS
 #   0  Directory created or already exists
 #   1  No target directory specified or mkdir failed
 #

functions/_prune_terminal_logs.fish

@@ -20,7 +20,7 @@
 # ARGUMENTS
 #   prefix  Log-name prefix to prune (e.g. tmux, zellij)
 #
-# RETURNS
+# EXIT STATUS
 #   0  Always
 #
 # EXAMPLE

functions/_qalc_eval.fish

@@ -10,7 +10,7 @@
 #   after evaluation. No-ops if qalc is not installed or the buffer
 #   is empty. Intended to be bound to a key in key_bindings.fish.
 #
-# RETURNS
+# EXIT STATUS
 #   1  qalc not found in PATH
 #
 # EXAMPLE

functions/_tmux_pipe_log.fish

@@ -12,7 +12,7 @@
 #   unset) or tmux is missing. Shared by conf.d/tmux-logging.fish (shell
 #   startup) and __fish_config_sync_logging (C5 re-enable) so both stay in sync.
 #
-# RETURNS
+# EXIT STATUS
 #   0  Always
 #
 # EXAMPLE

functions/_zellij_dump_log.fish

@@ -17,7 +17,7 @@
 #   No-op when logging is disabled, not inside Zellij ($ZELLIJ unset), or the
 #   zellij binary is missing.
 #
-# RETURNS
+# EXIT STATUS
 #   0  Always
 #
 # EXAMPLE

functions/agents-init.fish

@@ -66,7 +66,7 @@
 #   -s, --silent   Suppress all output; errors only (standard UNIX convention)
 #   -h, --help     Show this help message and exit
 #
-# RETURNS
+# EXIT STATUS
 #   0  Setup completed successfully
 #   1  Fatal error (git init failed, move failed, etc.)
 #

functions/agy.fish

@@ -25,7 +25,7 @@
 # ARGUMENTS
 #   ARGS  Any arguments forwarded verbatim to the underlying agy binary
 #
-# RETURNS
+# EXIT STATUS
 #   Exit status of the underlying agy binary
 #
 # EXAMPLE

functions/auto-pull.fish

@@ -29,7 +29,7 @@
 #   status             Show enabled/disabled state, repo count, and registry path
 #   -h, --help         Show this help message
 #
-# RETURNS
+# EXIT STATUS
 #   0  Subcommand succeeded
 #   1  Bad usage, target is not a git repo, or target not registered
 #

functions/bd-pull.fish

@@ -15,7 +15,7 @@
 # ARGUMENTS
 #   owner/repo  The repository path in owner/name format
 #
-# RETURNS
+# EXIT STATUS
 #   0  Issues linked and synced (or no unlinked issues found)
 #   1  Missing required argument or environment variables
 #

functions/bkg.fish

@@ -16,7 +16,7 @@
 #   command  The command to run detached
 #   args...  Additional arguments for the command
 #
-# RETURNS
+# EXIT STATUS
 #   0  Command launched successfully
 #   1  No command provided
 #

functions/branch.fish

@@ -14,7 +14,7 @@
 # ARGUMENTS
 #   branch_name   Branch to switch to or create
 #
-# RETURNS
+# EXIT STATUS
 #   0  Branch checked out or created
 #   1  Not inside a git work tree
 #

functions/claude.fish

@@ -25,7 +25,7 @@
 # ARGUMENTS
 #   ARGS  Any arguments forwarded verbatim to the underlying claude binary
 #
-# RETURNS
+# EXIT STATUS
 #   Exit status of the underlying claude binary
 #
 # EXAMPLE

functions/clone.fish

@@ -14,7 +14,7 @@
 # ARGUMENTS
 #   args...  Arguments forwarded to clone-in-kitty (typically a repo URL)
 #
-# RETURNS
+# EXIT STATUS
 #   0  Repository cloned
 #   1  Not running inside Kitty terminal
 #

functions/clonet.fish

@@ -14,7 +14,7 @@
 # ARGUMENTS
 #   args...  Arguments forwarded to clone-in-kitty (typically a repo URL)
 #
-# RETURNS
+# EXIT STATUS
 #   0  Repository cloned
 #   1  Not running inside Kitty terminal
 #

functions/config-help.fish

@@ -32,10 +32,14 @@
 #   -m, --man   Open the compiled man page via man -l
 #   -h, --help  Print usage and navigation reference, then exit
 #
-# RETURNS
-#   0  Manual displayed (or --help printed)
+# EXIT STATUS
+#   0  Manual displayed
 #   1  Documentation file not found, or required tool not available
 #
+# RETURNS
+#   With -h/--help, the usage and navigation reference, printed to stdout.
+#   Otherwise, the manual is shown via the resolved pager (not captured stdout).
+#
 # EXAMPLE
 #   config-help
 #   config-help keybindings

functions/config-settings.fish

@@ -56,7 +56,7 @@
 # ARGUMENTS
 #   -h, --help  Print usage and exit
 #
-# RETURNS
+# EXIT STATUS
 #   0  Exited normally (q or Escape pressed)
 #   1  Unknown flag passed
 #

functions/config-toggle.fish

@@ -17,7 +17,7 @@
 # ARGUMENTS
 #   args  Passed through verbatim to config-settings
 #
-# RETURNS
+# EXIT STATUS
 #   Same as config-settings
 #
 # EXAMPLE

functions/config-update.fish

@@ -18,7 +18,7 @@
 #   -f, --force     Stash local changes before pulling, then pop the stash
 #   -n, --dry-run   Check for upstream changes without applying them
 #
-# RETURNS
+# EXIT STATUS
 #   0  Config updated (or already up to date)
 #   1  Update failed (network error, merge conflict, or not a git repo)
 #

functions/detach.fish

@@ -18,7 +18,7 @@
 #   command      The command to run detached
 #   args...      Additional arguments for the command
 #
-# RETURNS
+# EXIT STATUS
 #   0  Command launched or help/version shown
 #   1  No command provided or unknown option
 #

functions/dng2avif.fish

@@ -19,7 +19,7 @@
 #   -s, --speed N       Encoder speed 0-10 (default: 3, 0 = slowest)
 #   -h, --help          Show help message
 #
-# RETURNS
+# EXIT STATUS
 #   0  Conversion complete
 #   1  File not found, missing dependency, or encode step failed
 #

functions/dockup.fish

@@ -15,7 +15,7 @@
 #   -h, --help   Show help message
 #   directory    Path to the compose project (defaults to current directory)
 #
-# RETURNS
+# EXIT STATUS
 #   0  Services updated and running
 #   1  Directory not found or no docker-compose.yml present
 #

functions/edit.fish

@@ -31,7 +31,7 @@
 #   -s, --silent      Suppress all output, including the editor's
 #   -h, --help        Show this help message
 #
-# RETURNS
+# EXIT STATUS
 #   0  Editor launched successfully
 #   1  Conflicting flags, no editor found, or clipboard read failed
 #

functions/fc.fish

@@ -16,7 +16,7 @@
 # ARGUMENTS
 #   command_prefix   Search history for the newest command matching this
 #
-# RETURNS
+# EXIT STATUS
 #   The edited command's exit status, or a message when history lookup
 #   found nothing.
 #

functions/fish-deps.fish

@@ -35,7 +35,7 @@
 #   update   Update all installed deps
 #   sync     Install missing deps, then update all
 #
-# RETURNS
+# EXIT STATUS
 #   0  Subcommand completed
 #   1  Unknown subcommand
 #

functions/fish_mode_prompt.fish

@@ -9,7 +9,7 @@
 #   that would prepend to the prompt line and break the two-line nim layout.
 #   Vi-mode display is handled inside fish_prompt itself.
 #
-# RETURNS
+# EXIT STATUS
 #   0  Always (function body is empty)
 #
 # EXAMPLE

functions/fish_prompt.fish

@@ -10,8 +10,11 @@
 #   C3 overrides are disabled. Has no external dependencies; uses only fish-provided functions
 #   (set_color, fish_git_prompt, prompt_pwd, prompt_hostname).
 #
+# EXIT STATUS
+#   0  Always
+#
 # RETURNS
-#   0  Always; outputs the prompt to stdout
+#   The rendered two-line prompt, printed to stdout
 #
 # EXAMPLE
 #   # Rendered automatically by fish; not called directly.

functions/fish_right_prompt.fish

@@ -11,7 +11,7 @@
 #   context (if non-default) — that block is paired with the starship prompt
 #   which already guards on both conditions.
 #
-# RETURNS
+# EXIT STATUS
 #   0  Always
 #
 # EXAMPLE

functions/fzf_configure_bindings.fish

@@ -19,7 +19,7 @@
 #   --variables=key   Override the variables search binding (default: Ctrl-V)
 #   -h, --help        Show help message
 #
-# RETURNS
+# EXIT STATUS
 #   0  Bindings installed or help shown
 #   22 Invalid option or positional argument provided
 #

functions/gi.fish

@@ -22,10 +22,14 @@
 #   -s, --stdout       Print API output to stdout instead of .gitignore
 #   targets            Comma- or space-separated list of language/tool names
 #
-# RETURNS
-#   0  Patterns appended or printed
+# EXIT STATUS
+#   0  Patterns appended, or resolved with -s/--stdout or -l/--list
 #   1  Not in a git repository or API fetch failed
 #
+# RETURNS
+#   With -s/--stdout, the fetched .gitignore pattern text, printed to stdout.
+#   With -l/--list, the supported target list, printed to stdout.
+#
 # EXAMPLE
 #   gi python,venv
 #   gi -b -p

functions/gip6.fish

@@ -11,10 +11,13 @@
 #   Fetches and prints the machine's public IPv6 address using icanhazip.com.
 #   Prints an error message if IPv6 is unavailable on the current network.
 #
-# RETURNS
-#   0  IPv6 address printed
+# EXIT STATUS
+#   0  IPv6 address resolved
 #   1  IPv6 unavailable or not supported on this network
 #
+# RETURNS
+#   The machine's public IPv6 address, printed to stdout
+#
 # EXAMPLE
 #   gip6
 function gip6 --description 'Get public IPv6 address'

functions/git-clean.fish

@@ -16,7 +16,7 @@
 #   -h, --help   Show help message
 #   -f, --force  Force-delete unmerged orphaned branches (git branch -D)
 #
-# RETURNS
+# EXIT STATUS
 #   0  Cleanup complete
 #   1  Argument parsing failed
 #

functions/gitup.fish

@@ -14,7 +14,7 @@
 # ARGUMENTS
 #   args...   Forwarded verbatim to git fetch
 #
-# RETURNS
+# EXIT STATUS
 #   0  Fetch and status succeeded
 #   1  Not inside a git work tree
 #

functions/joplin.fish

@@ -14,7 +14,7 @@
 # ARGUMENTS
 #   args...  Arguments forwarded to the joplin command
 #
-# RETURNS
+# EXIT STATUS
 #   0  Joplin ran successfully
 #   1  joplin binary not found in PATH
 #

functions/kitty-logging.fish

@@ -27,7 +27,7 @@
 #   dismiss    Stop the per-session reminder
 #   -h, --help Show this help
 #
-# RETURNS
+# EXIT STATUS
 #   0  Success
 #   1  Unknown subcommand/flag, kitty missing, or a write failure
 #

functions/logs.fish

@@ -25,7 +25,7 @@
 #   -h, --help           Show help message
 #   -c, --category cat   Filter to one category: scrollback, paru, or yay
 #
-# RETURNS
+# EXIT STATUS
 #   0  File viewed or no file selected
 #   1  No log files found
 #

functions/mkcd.fish

@@ -18,7 +18,7 @@
 #   -s, --silent  Suppress directory creation output
 #   <dir>         Directory to create and enter
 #
-# RETURNS
+# EXIT STATUS
 #   0  Directory created (or already existed) and entered successfully
 #   1  Directory creation or cd failed
 #

functions/open-url.fish

@@ -30,7 +30,7 @@
 #   -v, --verbose  Print which browser is being launched
 #   -h, --help     Print usage and exit
 #
-# RETURNS
+# EXIT STATUS
 #   0  Browser launched
 #   1  No URL given, invalid $BROWSER, or no browser found
 #

functions/p.fish

@@ -15,10 +15,13 @@
 #   -h, --help  Show usage help
 #   args...     Arguments forwarded to the clipboard tool
 #
-# RETURNS
-#   0  Clipboard contents printed successfully
+# EXIT STATUS
+#   0  Clipboard contents read successfully
 #   1  No supported clipboard tool found
 #
+# RETURNS
+#   The clipboard contents, printed to stdout
+#
 # EXAMPLE
 #   p | grep foo
 #   p > file.txt

functions/parur.fish

@@ -12,7 +12,7 @@
 #   pacman -Qi previews, then removes the selected packages using paru or yay.
 #   Arch Linux only.
 #
-# RETURNS
+# EXIT STATUS
 #   0  Packages removed or none selected
 #   1  No AUR helper (paru or yay) found
 #

functions/paste.fish

@@ -14,10 +14,13 @@
 # ARGUMENTS
 #   args...  Arguments forwarded to the clipboard tool
 #
-# RETURNS
-#   0  Clipboard contents printed successfully
+# EXIT STATUS
+#   0  Clipboard contents read successfully
 #   1  No supported clipboard tool found
 #
+# RETURNS
+#   The clipboard contents, printed to stdout
+#
 # EXAMPLE
 #   paste > file.txt
 function paste --description 'Paste from clipboard'

functions/pkg.fish

@@ -27,7 +27,7 @@
 #   -u, --uninstall  Force uninstall mode
 #   package          One or more package names to install or remove
 #
-# RETURNS
+# EXIT STATUS
 #   0  Operation completed
 #   1  No supported package manager found, unknown flag, or package operation failed
 #

functions/poke.fish

@@ -14,7 +14,7 @@
 # ARGUMENTS
 #   file  One or more file paths to create
 #
-# RETURNS
+# EXIT STATUS
 #   0  Files created
 #   1  No file argument provided
 #

functions/qc.fish

@@ -22,7 +22,7 @@
 #   prompt...     Prompt forwarded to aichat
 #   -h, --help    Show usage help
 #
-# RETURNS
+# EXIT STATUS
 #   aichat's exit status.
 #
 # EXAMPLE

functions/replay.fish

@@ -15,7 +15,7 @@
 # ARGUMENTS
 #   commands  Bash command string to execute and replay
 #
-# RETURNS
+# EXIT STATUS
 #   0  Commands ran successfully and changes were replayed
 #   1  Bash command exited with a non-zero status
 #

functions/repo-open.fish

@@ -37,10 +37,13 @@
 #   -r, --root   Ignore the current sub-directory; link to the repo root
 #   -h, --help   Print usage and exit
 #
-# RETURNS
-#   0  URL opened (or printed)
+# EXIT STATUS
+#   0  URL opened, or resolved with -p/--print
 #   1  Not a git repo, no origin remote, or browser launch failed
 #
+# RETURNS
+#   With -p/--print, the resolved repository URL, printed to stdout
+#
 # EXAMPLE
 #   repo-open              # open current branch (+ subdir) in browser
 #   repo-open --print      # just print the URL

functions/rm.fish

@@ -25,7 +25,7 @@
 #   -r, -R, --recursive Forwarded to trash put alongside path arguments
 #   args...             Files or paths to trash or remove
 #
-# RETURNS
+# EXIT STATUS
 #   0  Operation succeeded
 #   1  trash put failed or file not found
 #

functions/sbver.fish

@@ -16,7 +16,7 @@
 # ARGUMENTS
 #   --brief  Suppress per-file output; show only the final summary
 #
-# RETURNS
+# EXIT STATUS
 #   0  All binaries verified (or summary shown)
 #   1  sbctl is not installed
 #

functions/scrub.fish

@@ -19,7 +19,7 @@
 #   -d, --dry-run     Show targets without deleting
 #   -h, --help        Show usage help
 #
-# RETURNS
+# EXIT STATUS
 #   0  Sweep completed (or dry run shown)
 #   1  fd not found, or unknown argument provided
 #

functions/search.fish

@@ -14,7 +14,7 @@
 # ARGUMENTS
 #   args...  Arguments forwarded to paru or yay
 #
-# RETURNS
+# EXIT STATUS
 #   0  AUR helper ran successfully
 #   1  No AUR helper (paru or yay) found
 #

functions/smart_exit.fish

@@ -17,7 +17,7 @@
 #   -h, --help    Show help message
 #   -n, --no-log  Exit without saving a scrollback log
 #
-# RETURNS
+# EXIT STATUS
 #   0  Shell session exited
 #   1  Argument parsing failed
 #

functions/split.fish

@@ -18,7 +18,7 @@
 #   command...        Command to run in the new pane; opens a bare fish
 #                     shell if omitted
 #
-# RETURNS
+# EXIT STATUS
 #   0  Pane opened successfully
 #   1  Not running inside Kitty or WezTerm
 #

functions/sponge_filter_secrets.fish

@@ -21,7 +21,7 @@
 #   exit_code               Exit code of the command (unused)
 #   previously_in_history   "true"/"false" flag (unused)
 #
-# RETURNS
+# EXIT STATUS
 #   0  Command contains a secret value — filter out of history
 #   1  No secret value found — keep in history
 #

functions/spwin.fish

@@ -14,7 +14,7 @@
 # ARGUMENTS
 #   args...  Arguments forwarded to the spawn command
 #
-# RETURNS
+# EXIT STATUS
 #   0  Window opened successfully
 #   1  Not running inside Kitty or WezTerm
 #

functions/sudo-toggle.fish

@@ -13,7 +13,7 @@
 #   otherwise require a password entry. Clears the sudo credential cache
 #   when re-enabling, so the lockdown takes effect immediately.
 #
-# RETURNS
+# EXIT STATUS
 #   0  Rule toggled
 #
 # EXAMPLE

functions/superpowers.fish

@@ -18,7 +18,7 @@
 #   -g, --global  Apply at user/global scope instead of workspace/project
 #   -h, --help    Show usage help
 #
-# RETURNS
+# EXIT STATUS
 #   0  Mode applied successfully
 #   1  No on/off mode specified
 #

functions/tab.fish

@@ -15,7 +15,7 @@
 # ARGUMENTS
 #   args...  Arguments forwarded to the terminal's launch command
 #
-# RETURNS
+# EXIT STATUS
 #   0  Tab opened successfully
 #   1  No supported terminal found
 #

functions/upgrade.fish

@@ -11,7 +11,7 @@
 #   Runs a full system upgrade via paru or yay with --noconfirm. Falls
 #   back to yay if paru is not installed. Arch Linux only.
 #
-# RETURNS
+# EXIT STATUS
 #   0  Upgrade completed successfully
 #   1  No AUR helper (paru or yay) found
 #

functions/wake-lock.fish

@@ -15,7 +15,7 @@
 #   command  Command to run with sleep inhibition active
 #   args...  Arguments forwarded to the command
 #
-# RETURNS
+# EXIT STATUS
 #   0  Command ran and completed
 #   1  No command provided
 #

functions/y.fish

@@ -14,7 +14,7 @@
 # ARGUMENTS
 #   text  Text to copy; reads from stdin if omitted
 #
-# RETURNS
+# EXIT STATUS
 #   0  Text copied to clipboard
 #   1  No clipboard provider found
 #

functions/zoxide.fish

@@ -60,7 +60,7 @@ end
 # ARGUMENTS
 #   check  The string to compare against the first non-switch token
 #
-# RETURNS
+# EXIT STATUS
 #   0  First token equals check
 #   1  No token or token does not match
 #