chore: update configs, add .go-version

Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

.editorconfig-checker.json

@@ -1,9 +1,9 @@
 {
-  "Version": "2.7.0",
+  "Version": "v3.3.0",
   "Verbose": false,
   "Debug": false,
   "IgnoreDefaults": false,
-  "SpacesAftertabs": false,
+  "SpacesAfterTabs": false,
   "NoColor": false,
   "Exclude": [],
   "AllowedContentTypes": [],

.gitattributes

@@ -85,6 +85,7 @@ LICENSE           text
 NEWS              text
 readme            text
 *README*          text
+# Files literally named "TODO", not a todo list item
 TODO              text
 
 # Templates
@@ -122,7 +123,8 @@ package.json      text eol=lf
 package-lock.json text eol=lf -diff
 pnpm-lock.yaml    text eol=lf -diff
 .prettierrc       text
-yarn.lock         text -diff
+# Ensure yarn.lock shows textual diffs
+yarn.lock         text eol=lf
 *.toml            text
 *.yaml            text
 *.yml             text
@@ -251,3 +253,4 @@ install              text eol=lf diff=shell
 *.snippets           text eol=lf
 *.theme              text eol=lf
 *.yamlfmt            text eol=lf
+*.bats              text eol=lf diff=shell

.github/AGENTS.md

@@ -0,0 +1,30 @@
+# Guidelines for AI contributors
+
+These instructions help language models work with this repository.
+
+## Setup
+
+1. Run `yarn install` to get linting tools and the Bats test framework.
+
+## Formatting
+
+- Format code and docs with Prettier and markdownlint:
+
+```bash
+yarn fix:prettier
+yarn fix:markdown
+```
+
+- Shell scripts should pass `shellcheck`.
+
+## Testing
+
+- When code changes, run `yarn test` to execute Bats tests.
+- If only comments or documentation change, tests may be skipped.
+
+## Commits and PRs
+
+- Use Semantic Commit messages: `type(scope): summary`.
+- Keep PR titles in the same format.
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

.github/CODE_OF_CONDUCT.md

@@ -60,7 +60,7 @@ representative at an online or offline event.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported to the community leaders responsible for enforcement at
-ismo@ivuorinen.net.
+<ismo@ivuorinen.net>.
 All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the
@@ -116,7 +116,7 @@ the community.
 
 This Code of Conduct is adapted from the [Contributor Covenant][homepage],
 version 2.0, available at
-https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+<https://www.contributor-covenant.org/version/2/0/code_of_conduct.html>.
 
 Community Impact Guidelines were inspired by [Mozilla's code of conduct
 enforcement ladder](https://github.com/mozilla/diversity).
@@ -124,5 +124,5 @@ enforcement ladder](https://github.com/mozilla/diversity).
 [homepage]: https://www.contributor-covenant.org
 
 For answers to common questions about this code of conduct, see the FAQ at
-https://www.contributor-covenant.org/faq. Translations are available at
-https://www.contributor-covenant.org/translations.
+<https://www.contributor-covenant.org/faq>. Translations are available at
+<https://www.contributor-covenant.org/translations>.

.github/README.md

@@ -43,6 +43,12 @@ see what interesting stuff you've done with it. Sharing is caring.
 | `local/bin`         | Helper scripts that I've collected or wrote. |
 | `scripts`           | Setup scripts.                               |
 
+### Host specific configuration
+
+Configurations under `hosts/<hostname>` are applied only when running on the
+matching machine. Each host folder contains its own `install.conf.yaml` that
+is processed by Dotbot during installation.
+
 ### dotfile folders
 
 | Repo      | Destination | Description                                 |
@@ -58,6 +64,21 @@ see what interesting stuff you've done with it. Sharing is caring.
 
 Running `dfm` gives you a list of available commands.
 
+#### Documentation generation
+
+`dfm docs` generates Markdown documentation under the `docs/` directory. The
+subcommands are:
+
+```bash
+dfm docs alias        # regenerate alias table
+dfm docs folders      # document interesting folders
+dfm docs keybindings  # update keybinding docs for tmux, nvim and others
+dfm docs all          # run every docs task
+```
+
+The `docs/` folder contains generated cheat sheets, keybindings and other
+reference files. New documentation can be added without modifying this README.
+
 ## Configuration
 
 The folder structure follows [XDG Base Directory Specification][xdg] where possible.
@@ -73,6 +94,31 @@ The folder structure follows [XDG Base Directory Specification][xdg] where possi
 
 Please see [docs/folders.md][docs-folders] for more information.
 
+## Managing submodules
+
+This repository uses Git submodules for external dependencies. After cloning,
+run:
+
+```bash
+git submodule update --init --recursive
+```
+
+To pull submodule updates later use:
+
+```bash
+git submodule update --remote --merge
+```
+
+The helper script `add-submodules.sh` documents how each submodule is added and
+configured. Submodules are automatically updated by the
+[update-submodules.yml](.github/workflows/update-submodules.yml) workflow.
+
+## Testing
+
+Shell scripts under `local/bin` are validated with [Bats](https://github.com/bats-core/bats-core).
+Run `yarn test` to execute every test file. Bats is installed as a development
+dependency, so run `yarn install` first if needed.
+
 [dfm]: https://github.com/ivuorinen/dotfiles/blob/main/local/bin/dfm
 [docs-folders]: https://github.com/ivuorinen/dotfiles/blob/main/docs/folders.md
 [xdg]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html

.github/workflows/linters.yml

@@ -33,4 +33,4 @@ jobs:
 
       - name: Run PR Lint
         # https://github.com/ivuorinen/actions
-        uses: ivuorinen/actions/pr-lint@9480614ba2231013d99dd5b9c730d2b105b9e160 # 25.6.25
+        uses: ivuorinen/actions/pr-lint@8476cd4675ea8210eadf4a267bbeb13bddea4e75 # 25.7.21

.github/workflows/sync-labels.yml

@@ -29,4 +29,4 @@ jobs:
       issues: write
 
     steps:
-      - uses: ivuorinen/actions/sync-labels@99f3911475dbb5b8d43d314b24c0882997433868 # 25.6.23
+      - uses: ivuorinen/actions/sync-labels@8476cd4675ea8210eadf4a267bbeb13bddea4e75 # 25.7.21

.go-version

@@ -0,0 +1 @@
+1.23.0

.nvmrc

@@ -1 +1 @@
-22.17.0
+22.17.1

.pre-commit-config.yaml

@@ -39,7 +39,7 @@ repos:
       - id: shellcheck
 
   - repo: https://github.com/scop/pre-commit-shfmt
-    rev: v3.11.0-1
+    rev: v3.12.0-2
     hooks:
       - id: shfmt
 
@@ -49,7 +49,7 @@ repos:
       - id: actionlint
 
   - repo: https://github.com/renovatebot/pre-commit-hooks
-    rev: 41.11.1
+    rev: 41.43.0
     hooks:
       - id: renovate-config-validator
 

AGENTS.md

@@ -0,0 +1,34 @@
+# Project guidelines
+
+This repository contains configuration files and helper scripts for managing a development environment. Dotbot drives the installation and host specific folders under `hosts/` include extra configs.
+
+## Keeping the repository up to date
+
+1. Update submodules with `git submodule update --remote --merge`.
+2. Pull the latest changes and run `./install`.
+3. Run `yarn install` whenever `package.json` changes.
+
+## Linting and tests
+
+- Format files with:
+
+  ```bash
+  yarn fix:prettier
+  yarn fix:markdown
+  ```
+
+- Shell scripts must pass `shellcheck`. Run:
+
+  ```bash
+  find . -path ./node_modules -prune -o -name '*.sh' -print0 | xargs -0 shellcheck
+  ```
+
+- Execute tests with `yarn test`.
+
+## Debugging lint issues
+
+- `yarn lint:prettier` and `yarn lint:markdown` show formatting errors.
+- Ensure shell scripts have a shebang or `# shellcheck shell=bash` directive.
+- Consult `.shellcheckrc` for project specific checks.
+
+Scripts rely on helpers in `config/shared.sh` so they run under Bash, Zsh and Fish by default.

base/gitprofile

@@ -20,6 +20,16 @@
         "value": "Ismo Vuorinen"
       }
     ],
+    "masf": [
+      {
+        "key": "user.email",
+        "value": "ismo@masf.fi"
+      },
+      {
+        "key": "user.name",
+        "value": "Ismo Vuorinen"
+      }
+    ],
     "work": [
       {
         "key": "user.email",

config/asdf/golang-packages

@@ -1,8 +1,6 @@
 // These are golang packages I use,
 // so they should be available with all versions
 
-// Aqua is a package manager like asdf, or Brew
-github.com/aquaproj/aqua/v2/cmd/aqua@latest
 // Git Profile allows you to switch between user profiles in git repos
 github.com/dotzero/git-profile@v1.4.0
 // An extensible command line tool or library to format yaml files.
@@ -21,3 +19,8 @@ github.com/rhysd/actionlint/cmd/actionlint@v1.7.1
 github.com/doron-cohen/antidot@v0.6.3
 // FZF is a general-purpose command-line fuzzy finder.
 github.com/junegunn/fzf@latest
+// gopls, the Go language server
+golang.org/x/tools/gopls@latest
+// A language for writing HTML user interfaces in Go.
+github.com/a-h/templ/cmd/templ@latest
+

config/direnv/lib/use_asdf.sh

@@ -1,4 +1,5 @@
 ### Do not edit. This was autogenerated by 'asdf direnv setup' ###
+# shellcheck shell=bash
 use_asdf() {
   source_env "$(asdf direnv envrc "$@")"
 }

config/fish/completions/bob.fish

@@ -0,0 +1,71 @@
+# Print an optspec for argparse to handle cmd's options that are independent of any subcommand.
+function __fish_bob_global_optspecs
+	string join \n h/help V/version
+end
+
+function __fish_bob_needs_command
+	# Figure out if the current invocation already has a command.
+	set -l cmd (commandline -opc)
+	set -e cmd[1]
+	argparse -s (__fish_bob_global_optspecs) -- $cmd 2>/dev/null
+	or return
+	if set -q argv[1]
+		# Also print the command, so this can be used to figure out what it is.
+		echo $argv[1]
+		return 1
+	end
+	return 0
+end
+
+function __fish_bob_using_subcommand
+	set -l cmd (__fish_bob_needs_command)
+	test -z "$cmd"
+	and return 1
+	contains -- $cmd[1] $argv
+end
+
+complete -c bob -n "__fish_bob_needs_command" -s h -l help -d 'Print help'
+complete -c bob -n "__fish_bob_needs_command" -s V -l version -d 'Print version'
+complete -c bob -n "__fish_bob_needs_command" -f -a "use" -d 'Switch to the specified version, by default will auto-invoke install command if the version is not installed already'
+complete -c bob -n "__fish_bob_needs_command" -f -a "install" -d 'Install the specified version, can also be used to update out-of-date nightly version'
+complete -c bob -n "__fish_bob_needs_command" -f -a "sync" -d 'If Config::version_sync_file_location is set, the version in that file will be parsed and installed'
+complete -c bob -n "__fish_bob_needs_command" -f -a "uninstall" -d 'Uninstall the specified version'
+complete -c bob -n "__fish_bob_needs_command" -f -a "rm" -d 'Uninstall the specified version'
+complete -c bob -n "__fish_bob_needs_command" -f -a "rollback" -d 'Rollback to an existing nightly rollback'
+complete -c bob -n "__fish_bob_needs_command" -f -a "erase" -d 'Erase any change bob ever made, including neovim installation, neovim version downloads and registry changes'
+complete -c bob -n "__fish_bob_needs_command" -f -a "list" -d 'List all installed and used versions'
+complete -c bob -n "__fish_bob_needs_command" -f -a "ls" -d 'List all installed and used versions'
+complete -c bob -n "__fish_bob_needs_command" -f -a "list-remote"
+complete -c bob -n "__fish_bob_needs_command" -f -a "ls-remote"
+complete -c bob -n "__fish_bob_needs_command" -f -a "complete" -d 'Generate shell completion'
+complete -c bob -n "__fish_bob_needs_command" -f -a "update" -d 'Update existing version |nightly|stable|--all|'
+complete -c bob -n "__fish_bob_needs_command" -f -a "run"
+complete -c bob -n "__fish_bob_needs_command" -f -a "help" -d 'Print this message or the help of the given subcommand(s)'
+complete -c bob -n "__fish_bob_using_subcommand use" -s n -l no-install -d 'Whether not to auto-invoke install command'
+complete -c bob -n "__fish_bob_using_subcommand use" -s h -l help -d 'Print help (see more with \'--help\')'
+complete -c bob -n "__fish_bob_using_subcommand install" -s h -l help -d 'Print help (see more with \'--help\')'
+complete -c bob -n "__fish_bob_using_subcommand sync" -s h -l help -d 'Print help'
+complete -c bob -n "__fish_bob_using_subcommand uninstall" -s h -l help -d 'Print help (see more with \'--help\')'
+complete -c bob -n "__fish_bob_using_subcommand rm" -s h -l help -d 'Print help (see more with \'--help\')'
+complete -c bob -n "__fish_bob_using_subcommand rollback" -s h -l help -d 'Print help'
+complete -c bob -n "__fish_bob_using_subcommand erase" -s h -l help -d 'Print help'
+complete -c bob -n "__fish_bob_using_subcommand list" -s h -l help -d 'Print help'
+complete -c bob -n "__fish_bob_using_subcommand ls" -s h -l help -d 'Print help'
+complete -c bob -n "__fish_bob_using_subcommand list-remote" -s h -l help -d 'Print help'
+complete -c bob -n "__fish_bob_using_subcommand ls-remote" -s h -l help -d 'Print help'
+complete -c bob -n "__fish_bob_using_subcommand complete" -s h -l help -d 'Print help'
+complete -c bob -n "__fish_bob_using_subcommand update" -s a -l all -d 'Apply the update to all versions'
+complete -c bob -n "__fish_bob_using_subcommand update" -s h -l help -d 'Print help'
+complete -c bob -n "__fish_bob_using_subcommand run" -s h -l help -d 'Print help'
+complete -c bob -n "__fish_bob_using_subcommand help; and not __fish_seen_subcommand_from use install sync uninstall rollback erase list list-remote complete update run help" -f -a "use" -d 'Switch to the specified version, by default will auto-invoke install command if the version is not installed already'
+complete -c bob -n "__fish_bob_using_subcommand help; and not __fish_seen_subcommand_from use install sync uninstall rollback erase list list-remote complete update run help" -f -a "install" -d 'Install the specified version, can also be used to update out-of-date nightly version'
+complete -c bob -n "__fish_bob_using_subcommand help; and not __fish_seen_subcommand_from use install sync uninstall rollback erase list list-remote complete update run help" -f -a "sync" -d 'If Config::version_sync_file_location is set, the version in that file will be parsed and installed'
+complete -c bob -n "__fish_bob_using_subcommand help; and not __fish_seen_subcommand_from use install sync uninstall rollback erase list list-remote complete update run help" -f -a "uninstall" -d 'Uninstall the specified version'
+complete -c bob -n "__fish_bob_using_subcommand help; and not __fish_seen_subcommand_from use install sync uninstall rollback erase list list-remote complete update run help" -f -a "rollback" -d 'Rollback to an existing nightly rollback'
+complete -c bob -n "__fish_bob_using_subcommand help; and not __fish_seen_subcommand_from use install sync uninstall rollback erase list list-remote complete update run help" -f -a "erase" -d 'Erase any change bob ever made, including neovim installation, neovim version downloads and registry changes'
+complete -c bob -n "__fish_bob_using_subcommand help; and not __fish_seen_subcommand_from use install sync uninstall rollback erase list list-remote complete update run help" -f -a "list" -d 'List all installed and used versions'
+complete -c bob -n "__fish_bob_using_subcommand help; and not __fish_seen_subcommand_from use install sync uninstall rollback erase list list-remote complete update run help" -f -a "list-remote"
+complete -c bob -n "__fish_bob_using_subcommand help; and not __fish_seen_subcommand_from use install sync uninstall rollback erase list list-remote complete update run help" -f -a "complete" -d 'Generate shell completion'
+complete -c bob -n "__fish_bob_using_subcommand help; and not __fish_seen_subcommand_from use install sync uninstall rollback erase list list-remote complete update run help" -f -a "update" -d 'Update existing version |nightly|stable|--all|'
+complete -c bob -n "__fish_bob_using_subcommand help; and not __fish_seen_subcommand_from use install sync uninstall rollback erase list list-remote complete update run help" -f -a "run"
+complete -c bob -n "__fish_bob_using_subcommand help; and not __fish_seen_subcommand_from use install sync uninstall rollback erase list list-remote complete update run help" -f -a "help" -d 'Print this message or the help of the given subcommand(s)'

config/fish/completions/fzf_configure_bindings.fish

@@ -0,0 +1,8 @@
+complete fzf_configure_bindings --no-files
+complete fzf_configure_bindings --long help --short h --description "Print help" --condition "not __fish_seen_argument --help -h"
+complete fzf_configure_bindings --long directory --description "Change the key binding for Search Directory" --condition "not __fish_seen_argument --directory"
+complete fzf_configure_bindings --long git_log --description "Change the key binding for Search Git Log" --condition "not __fish_seen_argument --git_log"
+complete fzf_configure_bindings --long git_status --description "Change the key binding for Search Git Status" --condition "not __fish_seen_argument --git_status"
+complete fzf_configure_bindings --long history --description "Change the key binding for Search History" --condition "not __fish_seen_argument --history"
+complete fzf_configure_bindings --long processes --description "Change the key binding for Search Processes" --condition "not __fish_seen_argument --processes"
+complete fzf_configure_bindings --long variables --description "Change the key binding for Search Variables" --condition "not __fish_seen_argument --variables"

config/fish/completions/pinact.fish

@@ -0,0 +1,54 @@
+# pinact fish shell completion
+
+function __fish_pinact_no_subcommand --description 'Test if there has been any subcommand yet'
+    for i in (commandline -opc)
+        if contains -- $i init run migrate token version help-all help h completion
+            return 1
+        end
+    end
+    return 0
+end
+
+complete -c pinact -n '__fish_pinact_no_subcommand' -f -l log-level -r -d 'log level'
+complete -c pinact -n '__fish_pinact_no_subcommand' -f -l config -s c -r -d 'configuration file path'
+complete -c pinact -n '__fish_pinact_no_subcommand' -f -l help -s h -d 'show help'
+complete -c pinact -n '__fish_pinact_no_subcommand' -f -l version -s v -d 'print the version'
+complete -x -c pinact -n '__fish_pinact_no_subcommand' -a 'init' -d 'Create .pinact.yaml if it doesn\'t exist'
+complete -c pinact -n '__fish_seen_subcommand_from init' -f -l help -s h -d 'show help'
+complete -x -c pinact -n '__fish_seen_subcommand_from init; and not __fish_seen_subcommand_from help h' -a 'help' -d 'Shows a list of commands or help for one command'
+complete -x -c pinact -n '__fish_pinact_no_subcommand' -a 'run' -d 'Pin GitHub Actions versions'
+complete -c pinact -n '__fish_seen_subcommand_from run' -f -l verify -s v -d 'Verify if pairs of commit SHA and version are correct'
+complete -c pinact -n '__fish_seen_subcommand_from run' -f -l check -d 'Exit with a non-zero status code if actions are not pinned. If this is true, files aren\'t updated'
+complete -c pinact -n '__fish_seen_subcommand_from run' -f -l update -s u -d 'Update actions to latest versions'
+complete -c pinact -n '__fish_seen_subcommand_from run' -f -l review -d 'Create reviews'
+complete -c pinact -n '__fish_seen_subcommand_from run' -f -l fix -d 'Fix code. By default, this is true. If -check or -diff is true, this is false by default'
+complete -c pinact -n '__fish_seen_subcommand_from run' -f -l diff -d 'Output diff. By default, this is false'
+complete -c pinact -n '__fish_seen_subcommand_from run' -f -l repo-owner -r -d 'GitHub repository owner'
+complete -c pinact -n '__fish_seen_subcommand_from run' -f -l repo-name -r -d 'GitHub repository name'
+complete -c pinact -n '__fish_seen_subcommand_from run' -f -l sha -r -d 'Commit SHA to be reviewed'
+complete -c pinact -n '__fish_seen_subcommand_from run' -f -l pr -r -d 'GitHub pull request number'
+complete -c pinact -n '__fish_seen_subcommand_from run' -f -l help -s h -d 'show help'
+complete -x -c pinact -n '__fish_seen_subcommand_from run; and not __fish_seen_subcommand_from help h' -a 'help' -d 'Shows a list of commands or help for one command'
+complete -x -c pinact -n '__fish_pinact_no_subcommand' -a 'migrate' -d 'Migrate .pinact.yaml'
+complete -c pinact -n '__fish_seen_subcommand_from migrate' -f -l help -s h -d 'show help'
+complete -x -c pinact -n '__fish_seen_subcommand_from migrate; and not __fish_seen_subcommand_from help h' -a 'help' -d 'Shows a list of commands or help for one command'
+complete -x -c pinact -n '__fish_pinact_no_subcommand' -a 'token' -d 'Manage GitHub Access token'
+complete -c pinact -n '__fish_seen_subcommand_from token' -f -l help -s h -d 'show help'
+complete -x -c pinact -n '__fish_seen_subcommand_from token; and not __fish_seen_subcommand_from set remove rm help h' -a 'set' -d 'Set GitHub Access token'
+complete -c pinact -n '__fish_seen_subcommand_from token; and __fish_seen_subcommand_from set' -f -l stdin -d 'Read GitHub Access token from stdin'
+complete -c pinact -n '__fish_seen_subcommand_from token; and __fish_seen_subcommand_from set' -f -l help -s h -d 'show help'
+complete -x -c pinact -n '__fish_seen_subcommand_from token; and __fish_seen_subcommand_from set; and not __fish_seen_subcommand_from help h' -a 'help' -d 'Shows a list of commands or help for one command'
+complete -x -c pinact -n '__fish_seen_subcommand_from token; and not __fish_seen_subcommand_from set remove rm help h' -a 'remove' -d 'Remove GitHub Access token'
+complete -c pinact -n '__fish_seen_subcommand_from token; and __fish_seen_subcommand_from remove rm' -f -l help -s h -d 'show help'
+complete -x -c pinact -n '__fish_seen_subcommand_from token; and __fish_seen_subcommand_from remove rm; and not __fish_seen_subcommand_from help h' -a 'help' -d 'Shows a list of commands or help for one command'
+complete -x -c pinact -n '__fish_seen_subcommand_from token; and not __fish_seen_subcommand_from set remove rm help h' -a 'help' -d 'Shows a list of commands or help for one command'
+complete -x -c pinact -n '__fish_pinact_no_subcommand' -a 'version' -d 'Show version'
+complete -c pinact -n '__fish_seen_subcommand_from version' -f -l json -s j -d 'Output version in JSON format'
+complete -c pinact -n '__fish_seen_subcommand_from version' -f -l help -s h -d 'show help'
+complete -x -c pinact -n '__fish_seen_subcommand_from version; and not __fish_seen_subcommand_from help h' -a 'help' -d 'Shows a list of commands or help for one command'
+complete -c pinact -n '__fish_seen_subcommand_from help-all' -f -l help -s h -d 'show help'
+complete -x -c pinact -n '__fish_seen_subcommand_from help-all; and not __fish_seen_subcommand_from help h' -a 'help' -d 'Shows a list of commands or help for one command'
+complete -x -c pinact -n '__fish_pinact_no_subcommand' -a 'help' -d 'Shows a list of commands or help for one command'
+complete -x -c pinact -n '__fish_pinact_no_subcommand' -a 'completion' -d 'Output shell completion script for bash, zsh, fish, or Powershell'
+complete -c pinact -n '__fish_seen_subcommand_from completion' -f -l help -s h -d 'show help'
+complete -x -c pinact -n '__fish_seen_subcommand_from completion; and not __fish_seen_subcommand_from help h' -a 'help' -d 'Shows a list of commands or help for one command'

config/fish/conf.d/fzf.fish

@@ -0,0 +1,28 @@
+# fzf.fish is only meant to be used in interactive mode. If not in interactive mode and not in CI, skip the config to speed up shell startup
+if not status is-interactive && test "$CI" != true
+    exit
+end
+
+# Because of scoping rules, to capture the shell variables exactly as they are, we must read
+# them before even executing _fzf_search_variables. We use psub to store the
+# variables' info in temporary files and pass in the filenames as arguments.
+# This variable is global so that it can be referenced by fzf_configure_bindings and in tests
+set --global _fzf_search_vars_command '_fzf_search_variables (set --show | psub) (set --names | psub)'
+
+
+# Install the default bindings, which are mnemonic and minimally conflict with fish's preset bindings
+fzf_configure_bindings
+
+# Doesn't erase autoloaded _fzf_* functions because they are not easily accessible once key bindings are erased
+function _fzf_uninstall --on-event fzf_uninstall
+    _fzf_uninstall_bindings
+
+    set --erase _fzf_search_vars_command
+    functions --erase _fzf_uninstall _fzf_migration_message _fzf_uninstall_bindings fzf_configure_bindings
+    complete --erase fzf_configure_bindings
+
+    set_color cyan
+    echo "fzf.fish uninstalled."
+    echo "You may need to manually remove fzf_configure_bindings from your config.fish if you were using custom key bindings."
+    set_color normal
+end

config/fish/fish_plugins

@@ -8,3 +8,4 @@ edc/bass
 meaningful-ooo/sponge
 nickeb96/puffer-fish
 jgusta/paths
+patrickf1/fzf.fish

config/fish/functions/_fzf_configure_bindings_help.fish

@@ -0,0 +1,43 @@
+function _fzf_configure_bindings_help --description "Prints the help message for fzf_configure_bindings."
+    echo "\
+USAGE:
+    fzf_configure_bindings [--COMMAND=[KEY_SEQUENCE]...]
+
+DESCRIPTION
+    fzf_configure_bindings installs key bindings for fzf.fish's commands and erases any bindings it
+    previously installed. It installs bindings for both default and insert modes. fzf.fish executes
+    it without options on fish startup to install the out-of-the-box key bindings.
+
+    By default, commands are bound to a mnemonic key sequence, shown below. Each command's binding
+    can be configured using a namesake corresponding option:
+        COMMAND            |  DEFAULT KEY SEQUENCE         |  CORRESPONDING OPTION
+        Search Directory   |  Ctrl+Alt+F (F for file)      |  --directory
+        Search Git Log     |  Ctrl+Alt+L (L for log)       |  --git_log
+        Search Git Status  |  Ctrl+Alt+S (S for status)    |  --git_status
+        Search History     |  Ctrl+R     (R for reverse)   |  --history
+        Search Processes   |  Ctrl+Alt+P (P for process)   |  --processes
+        Search Variables   |  Ctrl+V     (V for variable)  |  --variables
+    Override a command's binding by specifying its corresponding option with the desired key
+    sequence. Disable a command's binding by specifying its corresponding option with no value.
+
+    Because fzf_configure_bindings erases bindings it previously installed, it can be cleanly
+    executed multiple times. Once the desired fzf_configure_bindings command has been found, add it
+    to your config.fish in order to persist the customized bindings.
+
+    In terms of validation, fzf_configure_bindings fails if passed unknown options. It expects an
+    equals sign between an option's name and value. However, it does not validate key sequences.
+
+    Pass -h or --help to print this help message and exit.
+
+EXAMPLES
+    Default bindings but bind Search Directory to Ctrl+F and Search Variables to Ctrl+Alt+V
+        \$ fzf_configure_bindings --directory=\cf --variables=\e\cv
+    Default bindings but disable Search History
+        \$ fzf_configure_bindings --history=
+    An agglomeration of different options
+        \$ fzf_configure_bindings --git_status=\cg --history=\ch --variables= --processes=
+
+SEE Also
+    To learn more about fish key bindings, see bind(1) and fish_key_reader(1).
+"
+end

config/fish/functions/_fzf_extract_var_info.fish

@@ -0,0 +1,15 @@
+# helper function for _fzf_search_variables
+function _fzf_extract_var_info --argument-names variable_name set_show_output --description "Extract and reformat lines pertaining to \$variable_name from \$set_show_output."
+    # Extract only the lines about the variable, all of which begin with either
+    # $variable_name: ...or... $variable_name[
+    string match --regex "^\\\$$variable_name(?::|\[).*" <$set_show_output |
+
+        # Strip the variable name prefix, including ": " for scope info lines
+        string replace --regex "^\\\$$variable_name(?:: )?" '' |
+
+        # Distill the lines of values, replacing...
+        #   [1]: |value|
+        # ...with...
+        #   [1] value
+        string replace --regex ": \|(.*)\|" ' $1'
+end

config/fish/functions/_fzf_preview_changed_file.fish

@@ -0,0 +1,49 @@
+# helper for _fzf_search_git_status
+# arg should be a line from git status --short, e.g.
+# MM functions/_fzf_preview_changed_file.fish
+#  D README.md
+# R  LICENSE -> "New License"
+function _fzf_preview_changed_file --argument-names path_status --description "Show the git diff of the given file."
+    # remove quotes because they'll be interpreted literally by git diff
+    # no need to requote when referencing $path because fish does not perform word splitting
+    # https://fishshell.com/docs/current/fish_for_bash_users.html
+    set -f path (string unescape (string sub --start 4 $path_status))
+    # first letter of short format shows index, second letter shows working tree
+    # https://git-scm.com/docs/git-status/2.35.0#_short_format
+    set -f index_status (string sub --length 1 $path_status)
+    set -f working_tree_status (string sub --start 2 --length 1 $path_status)
+
+    set -f diff_opts --color=always
+
+    if test $index_status = '?'
+        _fzf_report_diff_type Untracked
+        _fzf_preview_file $path
+    else if contains {$index_status}$working_tree_status DD AU UD UA DU AA UU
+        # Unmerged statuses taken directly from git status help's short format table
+        # Unmerged statuses are mutually exclusive with other statuses, so if we see
+        # these, then safe to assume the path is unmerged
+        _fzf_report_diff_type Unmerged
+        git diff $diff_opts -- $path
+    else
+        if test $index_status != ' '
+            _fzf_report_diff_type Staged
+
+            # renames are only detected in the index, never working tree, so only need to test for it here
+            # https://stackoverflow.com/questions/73954214
+            if test $index_status = R
+                # diff the post-rename path with the original path, otherwise the diff will show the entire file as being added
+                set -f orig_and_new_path (string split --max 1 -- ' -> ' $path)
+                git diff --staged $diff_opts -- $orig_and_new_path[1] $orig_and_new_path[2]
+                # path currently has the form of "original -> current", so we need to correct it before it's used below
+                set path $orig_and_new_path[2]
+            else
+                git diff --staged $diff_opts -- $path
+            end
+        end
+
+        if test $working_tree_status != ' '
+            _fzf_report_diff_type Unstaged
+            git diff $diff_opts -- $path
+        end
+    end
+end

config/fish/functions/_fzf_preview_file.fish

@@ -0,0 +1,43 @@
+# helper function for _fzf_search_directory and _fzf_search_git_status
+function _fzf_preview_file --description "Print a preview for the given file based on its file type."
+    # because there's no way to guarantee that _fzf_search_directory passes the path to _fzf_preview_file
+    # as one argument, we collect all the arguments into one single variable and treat that as the path
+    set -f file_path $argv
+
+    if test -L "$file_path" # symlink
+        # notify user and recurse on the target of the symlink, which can be any of these file types
+        set -l target_path (realpath "$file_path")
+
+        set_color yellow
+        echo "'$file_path' is a symlink to '$target_path'."
+        set_color normal
+
+        _fzf_preview_file "$target_path"
+    else if test -f "$file_path" # regular file
+        if set --query fzf_preview_file_cmd
+            # need to escape quotes to make sure eval receives file_path as a single arg
+            eval "$fzf_preview_file_cmd '$file_path'"
+        else
+            bat --style=numbers --color=always "$file_path"
+        end
+    else if test -d "$file_path" # directory
+        if set --query fzf_preview_dir_cmd
+            # see above
+            eval "$fzf_preview_dir_cmd '$file_path'"
+        else
+            # -A list hidden files as well, except for . and ..
+            # -F helps classify files by appending symbols after the file name
+            command ls -A -F "$file_path"
+        end
+    else if test -c "$file_path"
+        _fzf_report_file_type "$file_path" "character device file"
+    else if test -b "$file_path"
+        _fzf_report_file_type "$file_path" "block device file"
+    else if test -S "$file_path"
+        _fzf_report_file_type "$file_path" socket
+    else if test -p "$file_path"
+        _fzf_report_file_type "$file_path" "named pipe"
+    else
+        echo "$file_path doesn't exist." >&2
+    end
+end

config/fish/functions/_fzf_report_diff_type.fish

@@ -0,0 +1,18 @@
+# helper for _fzf_preview_changed_file
+# prints out something like
+# ╭────────╮
+# │ Staged │
+# ╰────────╯
+function _fzf_report_diff_type --argument-names diff_type --description "Print a distinct colored header meant to preface a git patch."
+    # number of "-" to draw is the length of the string to box + 2 for padding
+    set -f repeat_count (math 2 + (string length $diff_type))
+    set -f line (string repeat --count $repeat_count ─)
+    set -f top_border ╭$line╮
+    set -f btm_border ╰$line╯
+
+    set_color yellow
+    echo $top_border
+    echo "│ $diff_type │"
+    echo $btm_border
+    set_color normal
+end

config/fish/functions/_fzf_report_file_type.fish

@@ -0,0 +1,6 @@
+# helper function for _fzf_preview_file
+function _fzf_report_file_type --argument-names file_path file_type --description "Explain the file type for a file."
+    set_color red
+    echo "Cannot preview '$file_path': it is a $file_type."
+    set_color normal
+end

config/fish/functions/_fzf_search_directory.fish

@@ -0,0 +1,33 @@
+function _fzf_search_directory --description "Search the current directory. Replace the current token with the selected file paths."
+    # Directly use fd binary to avoid output buffering delay caused by a fd alias, if any.
+    # Debian-based distros install fd as fdfind and the fd package is something else, so
+    # check for fdfind first. Fall back to "fd" for a clear error message.
+    set -f fd_cmd (command -v fdfind || command -v fd  || echo "fd")
+    set -f --append fd_cmd --color=always $fzf_fd_opts
+
+    set -f fzf_arguments --multi --ansi $fzf_directory_opts
+    set -f token (commandline --current-token)
+    # expand any variables or leading tilde (~) in the token
+    set -f expanded_token (eval echo -- $token)
+    # unescape token because it's already quoted so backslashes will mess up the path
+    set -f unescaped_exp_token (string unescape -- $expanded_token)
+
+    # If the current token is a directory and has a trailing slash,
+    # then use it as fd's base directory.
+    if string match --quiet -- "*/" $unescaped_exp_token && test -d "$unescaped_exp_token"
+        set --append fd_cmd --base-directory=$unescaped_exp_token
+        # use the directory name as fzf's prompt to indicate the search is limited to that directory
+        set --prepend fzf_arguments --prompt="Directory $unescaped_exp_token> " --preview="_fzf_preview_file $expanded_token{}"
+        set -f file_paths_selected $unescaped_exp_token($fd_cmd 2>/dev/null | _fzf_wrapper $fzf_arguments)
+    else
+        set --prepend fzf_arguments --prompt="Directory> " --query="$unescaped_exp_token" --preview='_fzf_preview_file {}'
+        set -f file_paths_selected ($fd_cmd 2>/dev/null | _fzf_wrapper $fzf_arguments)
+    end
+
+
+    if test $status -eq 0
+        commandline --current-token --replace -- (string escape -- $file_paths_selected | string join ' ')
+    end
+
+    commandline --function repaint
+end

config/fish/functions/_fzf_search_git_log.fish

@@ -0,0 +1,36 @@
+function _fzf_search_git_log --description "Search the output of git log and preview commits. Replace the current token with the selected commit hash."
+    if not git rev-parse --git-dir >/dev/null 2>&1
+        echo '_fzf_search_git_log: Not in a git repository.' >&2
+    else
+        if not set --query fzf_git_log_format
+            # %h gives you the abbreviated commit hash, which is useful for saving screen space, but we will have to expand it later below
+            set -f fzf_git_log_format '%C(bold blue)%h%C(reset) - %C(cyan)%ad%C(reset) %C(yellow)%d%C(reset) %C(normal)%s%C(reset)  %C(dim normal)[%an]%C(reset)'
+        end
+
+        set -f preview_cmd 'git show --color=always --stat --patch {1}'
+        if set --query fzf_diff_highlighter
+            set preview_cmd "$preview_cmd | $fzf_diff_highlighter"
+        end
+
+        set -f selected_log_lines (
+            git log --no-show-signature --color=always --format=format:$fzf_git_log_format --date=short | \
+            _fzf_wrapper --ansi \
+                --multi \
+                --scheme=history \
+                --prompt="Git Log> " \
+                --preview=$preview_cmd \
+                --query=(commandline --current-token) \
+                $fzf_git_log_opts
+        )
+        if test $status -eq 0
+            for line in $selected_log_lines
+                set -f abbreviated_commit_hash (string split --field 1 " " $line)
+                set -f full_commit_hash (git rev-parse $abbreviated_commit_hash)
+                set -f --append commit_hashes $full_commit_hash
+            end
+            commandline --current-token --replace (string join ' ' $commit_hashes)
+        end
+    end
+
+    commandline --function repaint
+end

config/fish/functions/_fzf_search_git_status.fish

@@ -0,0 +1,41 @@
+function _fzf_search_git_status --description "Search the output of git status. Replace the current token with the selected file paths."
+    if not git rev-parse --git-dir >/dev/null 2>&1
+        echo '_fzf_search_git_status: Not in a git repository.' >&2
+    else
+        set -f preview_cmd '_fzf_preview_changed_file {}'
+        if set --query fzf_diff_highlighter
+            set preview_cmd "$preview_cmd | $fzf_diff_highlighter"
+        end
+
+        set -f selected_paths (
+            # Pass configuration color.status=always to force status to use colors even though output is sent to a pipe
+            git -c color.status=always status --short |
+            _fzf_wrapper --ansi \
+                --multi \
+                --prompt="Git Status> " \
+                --query=(commandline --current-token) \
+                --preview=$preview_cmd \
+                --nth="2.." \
+                $fzf_git_status_opts
+        )
+        if test $status -eq 0
+            # git status --short automatically escapes the paths of most files for us so not going to bother trying to handle
+            # the few edges cases of weird file names that should be extremely rare (e.g. "this;needs;escaping")
+            set -f cleaned_paths
+
+            for path in $selected_paths
+                if test (string sub --length 1 $path) = R
+                    # path has been renamed and looks like "R LICENSE -> LICENSE.md"
+                    # extract the path to use from after the arrow
+                    set --append cleaned_paths (string split -- "-> " $path)[-1]
+                else
+                    set --append cleaned_paths (string sub --start=4 $path)
+                end
+            end
+
+            commandline --current-token --replace -- (string join ' ' $cleaned_paths)
+        end
+    end
+
+    commandline --function repaint
+end

config/fish/functions/_fzf_search_history.fish

@@ -0,0 +1,39 @@
+function _fzf_search_history --description "Search command history. Replace the command line with the selected command."
+    # history merge incorporates history changes from other fish sessions
+    # it errors out if called in private mode
+    if test -z "$fish_private_mode"
+        builtin history merge
+    end
+
+    if not set --query fzf_history_time_format
+        # Reference https://devhints.io/strftime to understand strftime format symbols
+        set -f fzf_history_time_format "%m-%d %H:%M:%S"
+    end
+
+    # Delinate time from command in history entries using the vertical box drawing char (U+2502).
+    # Then, to get raw command from history entries, delete everything up to it. The ? on regex is
+    # necessary to make regex non-greedy so it won't match into commands containing the char.
+    set -f time_prefix_regex '^.*? │ '
+    # Delinate commands throughout pipeline using null rather than newlines because commands can be multi-line
+    set -f commands_selected (
+        builtin history --null --show-time="$fzf_history_time_format │ " |
+        _fzf_wrapper --read0 \
+            --print0 \
+            --multi \
+            --scheme=history \
+            --prompt="History> " \
+            --query=(commandline) \
+            --preview="string replace --regex '$time_prefix_regex' '' -- {} | fish_indent --ansi" \
+            --preview-window="bottom:3:wrap" \
+            $fzf_history_opts |
+        string split0 |
+        # remove timestamps from commands selected
+        string replace --regex $time_prefix_regex ''
+    )
+
+    if test $status -eq 0
+        commandline --replace -- $commands_selected
+    end
+
+    commandline --function repaint
+end

config/fish/functions/_fzf_search_processes.fish

@@ -0,0 +1,32 @@
+function _fzf_search_processes --description "Search all running processes. Replace the current token with the pid of the selected process."
+    # Directly use ps command because it is often aliased to a different command entirely
+    # or with options that dirty the search results and preview output
+    set -f ps_cmd (command -v ps || echo "ps")
+    # use all caps to be consistent with ps default format
+    # snake_case because ps doesn't seem to allow spaces in the field names
+    set -f ps_preview_fmt (string join ',' 'pid' 'ppid=PARENT' 'user' '%cpu' 'rss=RSS_IN_KB' 'start=START_TIME' 'command')
+    set -f processes_selected (
+        $ps_cmd -A -opid,command | \
+        _fzf_wrapper --multi \
+                    --prompt="Processes> " \
+                    --query (commandline --current-token) \
+                    --ansi \
+                    # first line outputted by ps is a header, so we need to mark it as so
+                    --header-lines=1 \
+                    # ps uses exit code 1 if the process was not found, in which case show an message explaining so
+                    --preview="$ps_cmd -o '$ps_preview_fmt' -p {1} || echo 'Cannot preview {1} because it exited.'" \
+                    --preview-window="bottom:4:wrap" \
+                    $fzf_processes_opts
+    )
+
+    if test $status -eq 0
+        for process in $processes_selected
+            set -f --append pids_selected (string split --no-empty --field=1 -- " " $process)
+        end
+
+        # string join to replace the newlines outputted by string split with spaces
+        commandline --current-token --replace -- (string join ' ' $pids_selected)
+    end
+
+    commandline --function repaint
+end

config/fish/functions/_fzf_search_variables.fish

@@ -0,0 +1,47 @@
+# This function expects the following two arguments:
+# argument 1 = output of (set --show | psub), i.e. a file with the scope info and values of all variables
+# argument 2 = output of (set --names | psub), i.e. a file with all variable names
+function _fzf_search_variables --argument-names set_show_output set_names_output --description "Search and preview shell variables. Replace the current token with the selected variable."
+    if test -z "$set_names_output"
+        printf '%s\n' '_fzf_search_variables requires 2 arguments.' >&2
+
+        commandline --function repaint
+        return 22 # 22 means invalid argument in POSIX
+    end
+
+    # Exclude the history variable from being piped into fzf because
+    # 1. it's not included in $set_names_output
+    # 2. it tends to be a very large value => increases computation time
+    # 3._fzf_search_history is a much better way to examine history anyway
+    set -f all_variable_names (string match --invert history <$set_names_output)
+
+    set -f current_token (commandline --current-token)
+    # Use the current token to pre-populate fzf's query. If the current token begins
+    # with a $, remove it from the query so that it will better match the variable names
+    set -f cleaned_curr_token (string replace -- '$' '' $current_token)
+
+    set -f variable_names_selected (
+        printf '%s\n' $all_variable_names |
+        _fzf_wrapper --preview "_fzf_extract_var_info {} $set_show_output" \
+            --prompt="Variables> " \
+            --preview-window="wrap" \
+            --multi \
+            --query=$cleaned_curr_token \
+            $fzf_variables_opts
+    )
+
+    if test $status -eq 0
+        # If the current token begins with a $, do not overwrite the $ when
+        # replacing the current token with the selected variable.
+        # Uses brace expansion to prepend $ to each variable name.
+        commandline --current-token --replace (
+            if string match --quiet -- '$*' $current_token
+                string join " " \${$variable_names_selected}
+            else
+                string join " " $variable_names_selected
+            end
+        )
+    end
+
+    commandline --function repaint
+end

config/fish/functions/_fzf_wrapper.fish

@@ -0,0 +1,21 @@
+function _fzf_wrapper --description "Prepares some environment variables before executing fzf."
+    # Make sure fzf uses fish to execute preview commands, some of which
+    # are autoloaded fish functions so don't exist in other shells.
+    # Use --function so that it doesn't clobber SHELL outside this function.
+    set -f --export SHELL (command --search fish)
+
+    # If neither FZF_DEFAULT_OPTS nor FZF_DEFAULT_OPTS_FILE are set, then set some sane defaults.
+    # See https://github.com/junegunn/fzf#environment-variables
+    set --query FZF_DEFAULT_OPTS FZF_DEFAULT_OPTS_FILE
+    if test $status -eq 2
+        # cycle allows jumping between the first and last results, making scrolling faster
+        # layout=reverse lists results top to bottom, mimicking the familiar layouts of git log, history, and env
+        # border shows where the fzf window begins and ends
+        # height=90% leaves space to see the current command and some scrollback, maintaining context of work
+        # preview-window=wrap wraps long lines in the preview window, making reading easier
+        # marker=* makes the multi-select marker more distinguishable from the pointer (since both default to >)
+        set --export FZF_DEFAULT_OPTS '--cycle --layout=reverse --border --height=90% --preview-window=wrap --marker="*"'
+    end
+
+    fzf $argv
+end

config/fish/functions/cr.fish

@@ -0,0 +1,303 @@
+# cr.fish — Create and manage code review worktrees for Fish shell
+#
+# Synopsis:
+#   cr [OPTIONS] <source-branch>
+#   cr cleanup [OPTIONS]
+#
+# Description:
+#   Create a dedicated worktree for reviewing code based on a ticket ID
+#   extracted from a branch name, or clean up existing cr- worktrees.
+#
+# Constants:
+#   CR_DEFAULT_REMOTE      Default Git remote used when none specified
+#
+# Fish Requirements:
+#   Fish shell >= 3.1.0 for argparse builtin
+#
+# Based on work by ville6000 (https://github.com/ville6000)
+#
+# Examples:
+#   cr feature/1234-add-login
+#   cr -r upstream 5678
+#   cr cleanup --dry-run
+
+if not set -q CR_DEFAULT_REMOTE
+    set -g CR_DEFAULT_REMOTE origin
+end
+
+function __cr_show_help
+    echo 'Usage: cr [OPTIONS] <source-branch>'
+    echo '       cr cleanup [OPTIONS]'
+    echo
+    echo "  -r, --remote <name>        Git remote (default: $CR_DEFAULT_REMOTE)"
+    echo '  -d, --dry-run              Show actions without executing'
+    echo '  -f, --force                Skip confirmation prompts'
+    echo '  -k, --keep-branch          In cleanup, keep local branches'
+    echo '  -b, --branch-only <ticket> Create only the review branch (no worktree)'
+    echo '      --cleanup-branches-only In cleanup, delete branches only'
+    echo '  -h, --help                 Show this help'
+end
+
+function __cr_run_with_spinner --argument-names msg cmd
+    set -l tmp (mktemp)
+    eval $cmd >$tmp 2>&1 &
+    set -l pid $last_pid
+    set -l spin_chars '/-\|'
+    set -l i 1
+    while kill -0 $pid 2>/dev/null
+        printf "\r[%c] %s" (string sub -s $i -l 1 $spin_chars) "$msg"
+        set i (math (math $i % 4) + 1)
+        sleep 0.1
+    end
+    printf "\r%s\r" (string repeat -n (math (string length "$msg") + 5) " ")
+    wait $pid
+    set -l output (cat $tmp)
+    rm $tmp
+    # Remove any leading empty or all-whitespace lines (from spinner clear)
+    for line in $output
+        if test -n (string trim -- $line)
+            echo $line
+        end
+    end
+end
+
+function __cr_cleanup
+    argparse dry_run force keep_branch cleanup_branches_only -- $argv
+    or return
+
+    set -l dry_run (set -q _flag_dry_run; and echo 1; or echo 0)
+    set -l force (set -q _flag_force; and echo 1; or echo 0)
+    set -l keep_branch (set -q _flag_keep_branch; and echo 1; or echo 0)
+    set -l branches_only (set -q _flag_cleanup_branches_only; and echo 1; or echo 0)
+
+    set -l target_branch
+    if test (count $argv) -gt 0
+        set target_branch $argv[1]
+    end
+
+    git worktree prune
+
+    for wt in (git worktree list --porcelain | awk '/^worktree /{print $2}')
+        set -l base (basename $wt)
+        if string match -r '^cr-.*' $base
+            if test -n "$target_branch" -a "$base" != "$target_branch"
+                continue
+            end
+            if test "$branches_only" = 0
+                if test "$dry_run" = 1
+                    echo "[DRY-RUN] remove worktree: $wt"
+                else if test "$force" = 1
+                    git worktree remove --force $wt
+                else
+                    echo "git worktree remove --force $wt"
+                    echo "(!) Use --force to actually remove worktree: $wt."
+                end
+            end
+            if test "$keep_branch" = 0
+                if test "$branches_only" = 0
+                    if test "$dry_run" = 1
+                        echo "[DRY-RUN] delete branch: $base"
+                    else if test "$force" = 1
+                        git branch -D $base
+                    else
+                        echo "git branch -D $base"
+                        echo "(!) Use --force to actually delete branch: $base."
+                    end
+                end
+            end
+        end
+    end
+end
+
+# --- Main Entrypoint ---
+
+function cr --description 'Create or cleanup code-review worktrees'
+    if not git rev-parse --is-inside-work-tree >/dev/null 2>&1
+        echo "Not inside a git repository." >&2
+        return 1
+    end
+
+    set -l remotes (git remote)
+    if test (count $remotes) -eq 0
+        echo "No git remotes found. Please add a remote before using cr." >&2
+        return 1
+    end
+
+    if not type -q argparse
+        echo 'cr.fish requires the argparse builtin' >&2
+        return 1
+    end
+
+    argparse \
+        r/remote= \
+        h/help \
+        d/dry-run \
+        f/force \
+        y/yes \
+        k/keep-branch \
+        b/branch-only= \
+        cleanup-branches-only \
+        -- $argv
+    or return
+
+    if set -q _flag_h; or set -q _flag_help
+        __cr_show_help
+        return 0
+    end
+
+    set -l remote (set -q _flag_remote; and echo $_flag_remote[-1]; or echo $CR_DEFAULT_REMOTE)
+    if set -q _flag_yes
+        set -g _flag_force 1
+    end
+
+    if not contains $remote $remotes
+        echo "Remote '$remote' does not exist. Available remotes: $remotes" >&2
+        return 1
+    end
+
+    if test (count $argv) -gt 0 -a "$argv[1]" = cleanup
+        __cr_cleanup \
+            (set -q _flag_dry_run; and echo --dry_run) \
+            (set -q _flag_force; and echo --force) \
+            (set -q _flag_keep_branch; and echo --keep_branch) \
+            (set -q _flag_cleanup_branches_only; and echo --cleanup_branches_only)
+        return 0
+    end
+
+    set -l source_branch ""
+    if test (count $argv) -gt 0
+        set source_branch $argv[1]
+    else if type -q fzf
+        set -l branches (__cr_run_with_spinner "Fetching branches..." \
+            "git ls-remote --heads $remote | sed 's|.*refs/heads/||'")
+        printf "\n"
+        if test (count $branches) -eq 0
+            echo "No branches found on remote '$remote'." >&2
+            return 1
+        end
+        set -l exclude_branches main master develop dev trunk
+        set -l filtered_branches
+        for b in $branches
+            set b (string trim -- $b)
+            if not contains -- $b $exclude_branches
+                set filtered_branches $filtered_branches $b
+            end
+        end
+        set source_branch (printf '%s\n' $filtered_branches | fzf --prompt='Select branch: ')
+        echo "Selected branch: $source_branch"
+        if test $status -ne 0
+            echo 'Selection aborted' >&2
+            return 1
+        end
+        if test -z "$source_branch"
+            echo 'No branch selected' >&2
+            return 1
+        end
+    else
+        __cr_show_help >&2
+        return 1
+    end
+
+    # Extract ticket ID from branch name, or use slug if not found
+    set -l branch_tail (string split "/" $source_branch)[-1]
+    set -l ticket_id (printf '%s\n' $branch_tail | grep -o '[0-9]\+' | tail -n1)
+    set -l review_suffix ""
+    if test -z "$ticket_id"
+        # No numeric ticket, use slug of branch name as suffix
+        set review_suffix (string replace -ra '[^a-zA-Z0-9]+' '-' -- $source_branch)
+    else
+        set review_suffix $ticket_id
+    end
+    if set -q _flag_b; or set -q _flag_branch_only
+        set review_suffix $_flag_branch_only[-1]
+    end
+    set -l review_branch cr-$review_suffix
+    set -l folder ../$review_branch
+
+    # Branch-only mode
+    if set -q _flag_b; or set -q _flag_branch_only
+        if set -q _flag_dry_run
+            echo "[DRY-RUN] Create branch $review_branch from $remote/$source_branch"
+            return 0
+        end
+        __cr_run_with_spinner "Fetching from $remote..." \
+            "git fetch $remote $source_branch"
+        git branch $review_branch $remote/$source_branch
+        echo "Created branch $review_branch"
+        return 0
+    end
+
+    __cr_run_with_spinner "Checking remote branch..." \
+        "git ls-remote --exit-code --heads $remote $source_branch >/dev/null 2>&1"
+    if test $status -ne 0
+        echo "No remote branch $remote/$source_branch" >&2
+        return 1
+    end
+    if git show-ref --quiet refs/heads/$review_branch
+        echo "Local branch $review_branch exists" >&2
+        return 1
+    end
+    if test -d $folder
+        echo "Directory $folder exists" >&2
+        return 1
+    end
+
+    if set -q _flag_dry_run
+        echo "[DRY-RUN] Add worktree $folder -b $review_branch $remote/$source_branch"
+        return 0
+    end
+
+    __cr_run_with_spinner "Fetching from $remote..." \
+        "git fetch $remote $source_branch"
+    git worktree add $folder -b $review_branch $remote/$source_branch
+end
+
+# --- Completion Functions ---
+
+complete -c cr -l help -s h -f -d 'Show help'
+complete -c cr -l remote -s r -f -d 'Git remote' -a '(git remote)'
+complete -c cr -l dry-run -s d -f -d 'Dry run'
+complete -c cr -l force -s f -f -d 'Skip confirmations'
+complete -c cr -l keep-branch -s k -f -d 'Keep branches in cleanup'
+complete -c cr -l branch-only -s b -f -d 'Branch-only mode' \
+    -a '(__fish_cr_ticket_ids)'
+complete -c cr -l cleanup-branches-only -f -d 'Branches-only cleanup'
+complete -c cr -f -a cleanup -d 'Cleanup mode' \
+    -n 'not __fish_seen_subcommand_from cleanup'
+complete -c cr -n '__fish_seen_subcommand_from cleanup' -f \
+    -a '(__fish_cr_cleanup_branches)' -d 'cr-* branch'
+complete -c cr -n '__fish_seen_subcommand_from cleanup' -f
+complete -c cr -n 'not __fish_seen_subcommand_from cleanup' -f \
+    -a '(__fish_cr_branches)' -d 'Source branch'
+
+function __fish_cr_cleanup_branches
+    git worktree list --porcelain | awk '/^worktree /{print $2}' | while read -l wt
+        set base (basename $wt)
+        if string match -r '^cr-.*' $base
+            echo $base
+        end
+    end
+end
+
+function __fish_cr_branches --description 'List remote branches'
+    set -l exclude_branches main master develop dev trunk
+    set -l branches (git ls-remote --heads $CR_DEFAULT_REMOTE | \
+        sed 's|.*refs/heads/||')
+    for b in $branches
+        set b (string trim -- $b)
+        if not contains -- $b $exclude_branches
+            echo $b
+        end
+    end
+end
+
+function __fish_cr_ticket_ids --description 'List ticket IDs from remote branches'
+    for b in (git ls-remote --heads $CR_DEFAULT_REMOTE | \
+        sed 's|.*refs/heads/||')
+        set b (string trim -- $b)
+        set -l id (string match -r '[0-9]+' -- $b)
+        if test -n "$id"
+            echo $id
+        end
+    end
+end

config/fish/functions/fzf_configure_bindings.fish

@@ -0,0 +1,46 @@
+# Always installs bindings for insert and default mode for simplicity and b/c it has almost no side-effect
+# https://gitter.im/fish-shell/fish-shell?at=60a55915ee77a74d685fa6b1
+function fzf_configure_bindings --description "Installs the default key bindings for fzf.fish with user overrides passed as options."
+    # no need to install bindings if not in interactive mode or running tests
+    status is-interactive || test "$CI" = true; or return
+
+    set -f options_spec h/help 'directory=?' 'git_log=?' 'git_status=?' 'history=?' 'processes=?' 'variables=?'
+    argparse --max-args=0 --ignore-unknown $options_spec -- $argv 2>/dev/null
+    if test $status -ne 0
+        echo "Invalid option or a positional argument was provided." >&2
+        _fzf_configure_bindings_help
+        return 22
+    else if set --query _flag_help
+        _fzf_configure_bindings_help
+        return
+    else
+        # Initialize with default key sequences and then override or disable them based on flags
+        # index 1 = directory, 2 = git_log, 3 = git_status, 4 = history, 5 = processes, 6 = variables
+        set -f key_sequences \e\cf \e\cl \e\cs \cr \e\cp \cv # \c = control, \e = escape
+        set --query _flag_directory && set key_sequences[1] "$_flag_directory"
+        set --query _flag_git_log && set key_sequences[2] "$_flag_git_log"
+        set --query _flag_git_status && set key_sequences[3] "$_flag_git_status"
+        set --query _flag_history && set key_sequences[4] "$_flag_history"
+        set --query _flag_processes && set key_sequences[5] "$_flag_processes"
+        set --query _flag_variables && set key_sequences[6] "$_flag_variables"
+
+        # If fzf bindings already exists, uninstall it first for a clean slate
+        if functions --query _fzf_uninstall_bindings
+            _fzf_uninstall_bindings
+        end
+
+        for mode in default insert
+            test -n $key_sequences[1] && bind --mode $mode $key_sequences[1] _fzf_search_directory
+            test -n $key_sequences[2] && bind --mode $mode $key_sequences[2] _fzf_search_git_log
+            test -n $key_sequences[3] && bind --mode $mode $key_sequences[3] _fzf_search_git_status
+            test -n $key_sequences[4] && bind --mode $mode $key_sequences[4] _fzf_search_history
+            test -n $key_sequences[5] && bind --mode $mode $key_sequences[5] _fzf_search_processes
+            test -n $key_sequences[6] && bind --mode $mode $key_sequences[6] "$_fzf_search_vars_command"
+        end
+
+        function _fzf_uninstall_bindings --inherit-variable key_sequences
+            bind --erase -- $key_sequences
+            bind --erase --mode insert -- $key_sequences
+        end
+    end
+end

config/git/ignore

@@ -21,3 +21,5 @@ dfm.sh
 .scannerwork
 .phpactor.json
 .zsh_history
+**/.claude/settings.local.json
+

config/git/shared

@@ -3,7 +3,7 @@
   helper = cache --timeout 30000
 
 [core]
-  excludesfile = ~/.config/git/gitignore
+  excludesfile = ~/.config/git/ignore
 
 [init]
   defaultBranch = main

config/htop/htoprc

@@ -1,6 +1,6 @@
 # Beware! This file is rewritten by htop when settings are changed in the interface.
 # The parser is also very primitive, and not human-friendly.
-htop_version=3.3.0
+htop_version=3.4.1
 config_reader_min_version=3
 fields=0 48 17 18 38 39 2 46 47 49 1
 hide_kernel_threads=1
@@ -25,6 +25,7 @@ detailed_cpu_time=0
 cpu_count_from_one=0
 show_cpu_usage=1
 show_cpu_frequency=0
+show_cached_memory=1
 update_process_names=0
 account_guest_in_cpu_meter=0
 color_scheme=0

config/nvim/lua/plugins/code.lua

@@ -11,6 +11,13 @@ return {
     end,
   },
 
+  -- Go development plugin for Vim
+  -- https://github.com/fatih/vim-go
+  {
+    'fatih/vim-go',
+    config = function() end,
+  },
+
   -- Run your tests at the speed of thought
   -- https://github.com/vim-test/vim-test
   {

config/nvim/lua/plugins/conform.lua

@@ -1,13 +1,18 @@
 return {
   {
     'stevearc/conform.nvim',
-    event = 'BufWritePre',
+    event = { 'BufReadPre', 'BufNewFile' },
     config = function()
       local conform = require 'conform'
 
       conform.setup {
         formatters_by_ft = {
+          bash = { 'shfmt' },
+          go = { 'golangci-lint' },
           lua = { 'stylua' },
+          sh = { 'shfmt' },
+          ansible = { 'ansible-lint' },
+          docker = { 'hadolint' },
         },
         format_on_save = function(bufnr)
           -- Disable autoformat for files in a certain paths
@@ -20,6 +25,7 @@ return {
           }
           return {
             lsp_fallback = not disable_lsp[vim.bo[bufnr].filetype],
+            async = false,
             timeout_ms = 500,
           }
         end,
@@ -63,4 +69,8 @@ return {
       end
     end,
   },
+  {
+    'gpanders/editorconfig.nvim',
+    lazy = false,
+  },
 }

config/nvim/lua/plugins/folke.lua

@@ -1,44 +1,4 @@
 return {
-  -- A collection of small QoL plugins for Neovim
-  -- https://github.com/folke/snacks.nvim
-  {
-    ---@module 'snacks'
-    'folke/snacks.nvim',
-    priority = 1000,
-    lazy = false,
-    ---@type snacks.Config
-    opts = {
-      bigfile = { enabled = true },
-      input = { enabled = true },
-      notifier = {
-        enabled = true,
-        timeout = 3000,
-      },
-      gitbrowse = { enabled = true },
-      quickfile = { enabled = true },
-      statuscolumn = {
-        enabled = true,
-        left = { 'mark', 'sign' }, -- priority of signs on the left (high to low)
-        right = { 'fold', 'git' }, -- priority of signs on the right (high to low)
-        folds = {
-          open = true, -- show open fold icons
-          git_hl = true, -- use Git Signs hl for fold icons
-        },
-        git = {
-          -- patterns to match Git signs
-          patterns = { 'GitSign', 'MiniDiffSign' },
-        },
-        refresh = 50, -- refresh at most every 50ms
-      },
-      words = { enabled = true },
-      styles = {
-        notification = {
-          wo = { wrap = true }, -- Wrap notifications
-        },
-      },
-    },
-  },
-
   -- Highly experimental plugin that completely
   -- replaces the UI for messages, cmdline and the popupmenu.
   -- https://github.com/folke/noice.nvim
@@ -49,7 +9,10 @@ return {
     dependencies = {
       -- if you lazy-load any plugin below, make sure to add proper `module="..."` entries
       'MunifTanjim/nui.nvim',
-      'rcarriga/nvim-notify',
+      {
+        'rcarriga/nvim-notify',
+        opts = { background_colour = '#000000' },
+      },
     },
     opts = {
       lsp = {
@@ -69,6 +32,10 @@ return {
         lsp_doc_border = false, -- add a border to hover docs and signature help
       },
       routes = {
+        {
+          view = 'notify',
+          filter = { event = 'msg_showmode' },
+        },
         {
           filter = {
             event = 'msg_show',
@@ -106,13 +73,31 @@ return {
       },
       views = {
         cmdline_popup = {
-          border = {
-            style = 'none',
-            padding = { 1, 2 },
+          position = {
+            row = 5,
+            col = '50%',
+          },
+          size = {
+            width = 60,
+            height = 'auto',
+          },
+        },
+        popupmenu = {
+          relative = 'editor',
+          position = {
+            row = 8,
+            col = '50%',
+          },
+          size = {
+            width = 60,
+            height = 10,
+          },
+          border = {
+            style = 'rounded',
+            padding = { 0, 1 },
           },
-          filter_options = {},
           win_options = {
-            winhighlight = 'NormalFloat:NormalFloat,FloatBorder:FloatBorder',
+            winhighlight = { Normal = 'Normal', FloatBorder = 'DiagnosticInfo' },
           },
         },
       },

config/nvim/lua/plugins/lsp.lua

@@ -17,6 +17,8 @@ return {
 
       -- Allows extra capabilities provided by blink.cmp
       'saghen/blink.cmp',
+
+      { 'j-hui/fidget.nvim', opts = {} },
     },
     config = function()
       local lazydev = require 'lazydev'

config/nvim/lua/plugins/ui.lua

@@ -1,7 +1,22 @@
 return {
   {
-    'rmehri01/onenord.nvim',
-    opts = {},
+    'rose-pine/neovim',
+    name = 'rose-pine',
+    opts = {
+      dim_inactive_windows = false,
+      extend_background_behind_borders = true,
+      styles = {
+        bold = true,
+        italic = true,
+        transparency = true,
+      },
+      enable = {
+        terminal = true,
+        legacy_highlights = true, -- Improve compatibility for previous versions of Neovim
+        migrations = true, -- Handle deprecated options automatically
+      },
+    },
+    config = function() vim.cmd 'colorscheme rose-pine' end,
   },
   -- Automatic dark mode
   -- https://github.com/f-person/auto-dark-mode.nvim
@@ -12,10 +27,12 @@ return {
       set_dark_mode = function()
         vim.api.nvim_set_option_value('background', 'dark', {})
         -- vim.cmd.colorscheme(vim.g.colors_variant_dark)
+        vim.cmd 'colorscheme rose-pine'
       end,
       set_light_mode = function()
         vim.api.nvim_set_option_value('background', 'light', {})
         -- vim.cmd.colorscheme(vim.g.colors_variant_light)
+        vim.cmd 'colorscheme rose-pine-dawn'
       end,
     },
   },
@@ -43,7 +60,16 @@ return {
         extra_groups = {
           'NormalNC',
           'NormalFloat',
+          'FloatTitle',
           'FloatBorder',
+          'NotifyDEBUGBorder',
+          'NotifyERRORBorder',
+          'NotifyINFOBorder',
+          'NotifyINFOBorder73',
+          'NotifyINFOBorder75',
+          'NotifyINFOBorder101',
+          'NotifyTRACEBorder',
+          'NotifyWARNBorder',
           'TelescopeBorder',
           'TelescopePromptBorder',
           'TelescopeResultsBorder',
@@ -68,6 +94,42 @@ return {
     'm4xshen/hardtime.nvim',
     lazy = false,
     dependencies = { 'MunifTanjim/nui.nvim' },
-    opts = {},
+    opts = {
+      restriction_mode = 'hint',
+      disabled_keys = {
+        ['<Up>'] = { '', 'n' },
+        ['<Down>'] = { '', 'n' },
+        ['<Left>'] = { '', 'n' },
+        ['<Right>'] = { '', 'n' },
+        ['<C-Up>'] = { '', 'n' },
+        ['<C-Down>'] = { '', 'n' },
+        ['<C-Left>'] = { '', 'n' },
+        ['<C-Right>'] = { '', 'n' },
+      },
+      disabled_filetypes = {
+        'TelescopePrompt',
+        'Trouble',
+        'lazy',
+        'mason',
+        'help',
+        'notify',
+        'dashboard',
+        'alpha',
+      },
+      hints = {
+        ['[dcyvV][ia][%(%)]'] = {
+          message = function(keys)
+            return 'Use ' .. keys:sub(1, 2) .. 'b instead of ' .. keys
+          end,
+          length = 3,
+        },
+        ['[dcyvV][ia][%{%}]'] = {
+          message = function(keys)
+            return 'Use ' .. keys:sub(1, 2) .. 'B instead of ' .. keys
+          end,
+          length = 3,
+        },
+      },
+    },
   },
 }

config/op/plugins.sh

@@ -1,2 +1,3 @@
+# shellcheck shell=bash
 export OP_PLUGIN_ALIASES_SOURCED=1
 alias gh="op plugin run -- gh"

config/op/plugins/used_items/gh.json

@@ -1 +1,7 @@
-[{"account_id":"S5Z2DMNFKJEZBPCWRHRWC4DCGI","vault_id":"injcin7obv3jdet3r2u3kfihfy","item_id":"f6vinbnc6l7ngdzvlw66ayewlq"}]
+[
+  {
+    "account_id": "S5Z2DMNFKJEZBPCWRHRWC4DCGI",
+    "vault_id": "injcin7obv3jdet3r2u3kfihfy",
+    "item_id": "f6vinbnc6l7ngdzvlw66ayewlq"
+  }
+]

config/shared.sh

@@ -26,7 +26,7 @@ x-path-prepend()
   local dir=$1
   case "$CURRENT_SHELL" in
     fish)
-      set -U fish_user_paths "$dir" $fish_user_paths
+      set -U fish_user_paths "$dir" "$fish_user_paths"
       ;;
     sh | bash | zsh)
       PATH="$dir:$PATH"
@@ -106,7 +106,7 @@ if ! declare -f msg_done > /dev/null; then
   # $1 - message (string)
   msg_done()
   {
-    msgr done "$1"
+    msgr "done" "$1"
     return 0
   }
 fi

config/tms/config.toml

@@ -1,10 +1,11 @@
 default_session = "main"
+display_full_path = true
 
 [[search_dirs]]
 path = "~/Code"
 depth = 3
 
 [picker_colors]
-highlight_color = "#21202e"
-highlight_text_color = "#86e1fc"
-border_color = "#524f67"
+highlight_color = "#21202E"
+highlight_text_color = "#86E1FC"
+border_color = "#524F67"

config/yabai/yabairc

@@ -25,6 +25,7 @@ yabai -m config \
 # > yabai -m query --windows | jq .[].app | sort | uniq
 yabai -m rule --add app="1Password" manage=off
 yabai -m rule --add app="Fork" manage=off
+yabai -m rule --add app="GoLand" manage=off
 yabai -m rule --add app="JetBrains Rider" manage=off
 yabai -m rule --add app="Logi Options" manage=off
 yabai -m rule --add app="MSTeams" manage=off

config/zed/settings.json

@@ -1,6 +1,7 @@
 {
   "context_servers": {
     "github-activity-summarizer": {
+      "source": "extension",
       "settings": {}
     }
   },
@@ -8,12 +9,13 @@
     "metrics": false
   },
   "agent": {
-    "always_allow_tool_actions": false,
+    "always_allow_tool_actions": true,
+    "default_profile": "write",
     "default_model": {
       "provider": "copilot_chat",
-      "model": "gpt-4.1"
+      "model": "claude-3.7-sonnet"
     },
-    "version": "2"
+    "play_sound_when_agent_done": true
   },
   "languages": {
     "PHP": {
@@ -35,14 +37,15 @@
     },
     "Markdown": {
       "enable_language_server": true,
-      "preferred_line_length": 160,
-      "prettier": {
-        "allowed": true
-      }
+      "preferred_line_length": 120,
+      "formatter": "language_server"
     },
     "Lua": {
       "enable_language_server": true,
       "tab_size": 2
+    },
+    "Go": {
+      "language_servers": ["gopls", "golangci-lint"]
     }
   },
   "lsp": {
@@ -77,7 +80,7 @@
       "update_debounce_ms": 150
     }
   },
-  "multi_cursor_modifier": "cmd_or_ctrl", // alias: "cmd", "ctrl"
+  "multi_cursor_modifier": "cmd_or_ctrl",
   "indent_guides": {
     "enabled": true,
     "coloring": "indent_aware"
@@ -89,8 +92,8 @@
   "vim_mode": true,
   "theme": {
     "mode": "system",
-    "light": "Tomorrow",
-    "dark": "Tomorrow at Midnight"
+    "light": "Rosé Pine Dawn",
+    "dark": "Rosé Pine"
   },
   "inlay_hints": {
     "enabled": true,
@@ -102,7 +105,6 @@
   "buffer_font_size": 16,
   "buffer_font_fallbacks": ["JetBrainsMono Nerd Font"],
   "use_autoclose": false,
-  "hour_format": "hour24",
   "auto_install_extensions": {
     "angular": true,
     "ansible": true,
@@ -114,9 +116,9 @@
     "dockerfile": true,
     "git-firefly": true,
     "github-activity-summarizer": true,
+    "go-snippets": true,
     "golangci-lint": true,
     "gosum": true,
-    "go-snippets": true,
     "html": true,
     "ini": true,
     "json": true,
@@ -126,19 +128,20 @@
     "lua": true,
     "make": true,
     "php": true,
-    "python-snippets": true,
     "python-requirements": true,
+    "python-snippets": true,
+    "rose-pine-theme": true,
     "ruff": true,
     "scss": true,
     "sieve": true,
-    "stylelint": true,
     "sql": true,
+    "stylelint": true,
+    "templ": true,
     "toml": true,
     "vue": true,
     "vue-snippets": true,
     "wakatime": true,
     "xcode-themes": true,
-    "yaml": true,
-    "tomorrow-theme": true
+    "yaml": true
   }
 }

hosts/README.md

@@ -0,0 +1,11 @@
+# Host specific directories
+
+Host folders contain machine specific overrides and an `install.conf.yaml` file that Dotbot processes during setup.
+
+Current hosts:
+
+- **air** – personal computer
+- **lakka** – remote server
+- **s** – work laptop
+- **tunkki** – local server
+- **v** – work desktop

local/bin/a.md

@@ -0,0 +1,29 @@
+# a
+
+Encrypt or decrypt files and directories using `age` and your GitHub SSH keys.
+
+## Usage
+
+```bash
+a encrypt <file|dir>
+a decrypt <file.age|dir>
+```
+
+Options:
+
+- `-v`, `--verbose` – show log output
+
+Environment variables:
+
+- `AGE_KEYSFILE` – location of the keys file
+- `AGE_KEYSSOURCE` – URL to fetch keys if missing
+- `AGE_LOGFILE` – log file path
+
+## Example
+
+```bash
+a encrypt secret.txt
+a decrypt secret.txt.age
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/ad.md

@@ -0,0 +1,19 @@
+# ad
+
+Decrypt a file encrypted with `age` using your GitHub SSH keys.
+
+## Usage
+
+```bash
+ad <file.age>
+```
+
+Uses `AGE_KEYSFILE` and `AGE_KEYSSOURCE` if keys are missing.
+
+## Example
+
+```bash
+ad secret.txt.age
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/ae.md

@@ -0,0 +1,19 @@
+# ae
+
+Encrypt a file with `age` using your GitHub SSH keys.
+
+## Usage
+
+```bash
+ae <file>
+```
+
+Uses `AGE_KEYSFILE` and `AGE_KEYSSOURCE` if keys are missing.
+
+## Example
+
+```bash
+ae secret.txt
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/dfm.md

@@ -0,0 +1,26 @@
+# dfm
+
+Dotfiles manager and installation helper. Provides wrappers for many
+setup tasks defined in this repository.
+
+## Usage
+
+```bash
+dfm <command> [options]
+```
+
+Common commands include:
+
+- `install` – install tools or run platform specific setup
+- `brew` – manage Homebrew packages
+- `docs` – regenerate markdown documentation
+
+Set `VERBOSE=1` to see debug output.
+
+### Example
+
+```bash
+dfm install all
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/fzf-tmux.md

@@ -0,0 +1,21 @@
+# fzf-tmux
+
+Wrapper around [`fzf`](https://github.com/junegunn/fzf) that opens the
+interface inside a tmux pane or popup.
+
+## Usage
+
+```bash
+fzf-tmux [layout options] [--] [fzf options]
+```
+
+Layout flags like `-p` or `-d` control popup and split behaviour. Use
+`--` to pass arguments directly to `fzf`.
+
+### Example
+
+```bash
+fzf-tmux -p 80%,60% -- --reverse
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/fzf.md

@@ -0,0 +1,16 @@
+# fzf
+
+Binary of the fuzzy finder [fzf](https://github.com/junegunn/fzf).
+Use `fzf` as you would normally; this wrapper ships the prebuilt
+binary in the dotfiles.
+
+## Usage
+
+```bash
+fzf [options]
+```
+
+Refer to the upstream `fzf` documentation for all available
+flags and features.
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/git-attributes.md

@@ -0,0 +1,25 @@
+# git-attributes
+
+Checks that every tracked file has a matching pattern in `.gitattributes`.
+Can optionally suggest or write missing rules.
+
+## Usage
+
+```bash
+git-attributes [options]
+```
+
+Options include:
+
+- `-v, --verbose` – show progress information
+- `-e, --exit` – exit with non-zero status if missing rules
+- `-p, --pattern <glob>` – pattern to check (default: `text: auto`)
+- `-w, --write` – append suggestions to `.gitattributes`
+
+### Example
+
+```bash
+git-attributes -v --write
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/iterm2_shell_integration.zsh.md

@@ -0,0 +1,15 @@
+# iterm2_shell_integration.zsh
+
+Official iTerm2 shell integration script for zsh. Source this file to
+enable prompt tracking and command notifications in iTerm2.
+
+## Usage
+
+```bash
+source iterm2_shell_integration.zsh
+```
+
+No parameters are required. The script modifies your prompt to work
+with iTerm2 features such as badges and profile switching.
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/msgr.md

@@ -0,0 +1,20 @@
+# msgr
+
+Helper library for printing colorized log messages from shell scripts.
+
+## Usage
+
+```bash
+msgr <type> "message" [extra]
+```
+
+Message types include `ok`, `warn`, `err`, `run` and many more. The
+script is primarily sourced by other scripts.
+
+### Example
+
+```bash
+msgr ok "Installation complete"
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/php-switcher.md

@@ -0,0 +1,23 @@
+# php-switcher
+
+Switch between Homebrew-installed PHP versions or list installed versions.
+
+## Usage
+
+```bash
+php-switcher <version>|--auto [options]
+```
+
+Options:
+
+- `--installed` – list versions installed via Homebrew
+- `--current` – print currently active PHP version
+- `--auto` – read version from `.php-version` in current directory
+
+### Example
+
+```bash
+php-switcher 8.3
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/pushover

@@ -56,22 +56,31 @@ __pushover_send_message()
 
   response="$(eval "${curl_cmd}")"
   printf "%s\n" "$response"
-  # TODO: Parse response
-  r="${?}"
-  if [ "${r}" -ne 0 ]; then
-    printf "%s: Failed to send message\n" "${0}" >&2
+
+  # Parse response status. Expect JSON like: {"status":1,"request":"..."}
+  if echo "$response" | grep -q '"status"[[:space:]]*:[[:space:]]*1'; then
+    r=0
+  else
+    r=1
   fi
 
-  return "${r}"
+  if [ "$r" -ne 0 ]; then
+    # Extract possible error message from JSON
+    err=$(echo "$response" | grep -o '"errors".*' | sed 's/"errors"[:,\[]//g' | tr -d '[]"')
+    [ -n "$err" ] && printf "%s: %s\n" "$0" "$err" >&2
+    printf "%s: Failed to send message\n" "$0" >&2
+  fi
+
+  return "$r"
 }
 
-CURL="$(which curl)"
+CURL="$(command -v curl)"
 PUSHOVER_URL="https://api.pushover.net/1/messages.json"
 TOKEN=$PUSHOVER_TOKEN
 USER=$PUSHOVER_USER
 CURL_OPTS=""
-devices="${devices} ${device}"
-optstring="c:d:D:e:f:p:r:t:T:s:u:U:a:h"
+devices=""
+optstring="c:d:D:e:p:r:t:T:s:u:U:a:h"
 
 OPTIND=1
 while getopts ${optstring} c; do
@@ -97,7 +106,7 @@ while getopts ${optstring} c; do
     t)
       title="${OPTARG}"
       ;;
-    k)
+    T)
       TOKEN="${OPTARG}"
       ;;
     s)

local/bin/pushover.md

@@ -0,0 +1,25 @@
+# pushover
+
+Send notifications via the Pushover API.
+
+## Usage
+
+```bash
+pushover -T <token> -U <user> [-t title] [-p priority] message
+```
+
+Common options:
+
+- `-c <callback>` – callback URL
+- `-d <device>` – target device
+- `-s <sound>` – notification sound name
+- `-T <token>` – application token (or `PUSHOVER_TOKEN` env)
+- `-U <user>` – user key (or `PUSHOVER_USER` env)
+
+## Example
+
+```bash
+pushover -T $TOKEN -U $USER -t "Build" "Finished successfully"
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/t.md

@@ -0,0 +1,23 @@
+# t
+
+Launch or switch to a tmux session based on a directory selected with
+`fzf`. Inspired by scripts from ThePrimeagen and Jess Archer.
+
+## Usage
+
+```bash
+t
+```
+
+Environment variables:
+
+- `T_ROOT` – base directory to search (default: `~/Code`)
+- `T_MAX_DEPTH` – recursion depth for directory search
+
+### Example
+
+```bash
+T_ROOT=~/projects t
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-backup-folder.md

@@ -0,0 +1,20 @@
+# x-backup-folder
+
+Create a compressed archive of a folder with a timestamped name.
+
+## Usage
+
+```bash
+x-backup-folder <folder> [archive-name]
+```
+
+- `folder` – directory to back up
+- `archive-name` – optional prefix for the generated tar.gz
+
+## Example
+
+```bash
+x-backup-folder ~/Documents Notes
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-backup-mysql-with-prefix.md

@@ -0,0 +1,21 @@
+# x-backup-mysql-with-prefix
+
+Dump MySQL tables matching a prefix to a timestamped file.
+
+## Usage
+
+```bash
+x-backup-mysql-with-prefix <prefix> <name> [database]
+```
+
+- `prefix` – table prefix to match (e.g. `wp_`)
+- `name` – file name prefix
+- `database` – database name (default: `wordpress`)
+
+## Example
+
+```bash
+x-backup-mysql-with-prefix wp_ blog
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-change-alacritty-theme.md

@@ -0,0 +1,20 @@
+# x-change-alacritty-theme
+
+Adapted from <https://gist.github.com/xqm32/17777d035930d622d0ff7530bfab61fd>
+
+## Usage
+
+```bash
+x-change-alacritty-theme <day|night>
+```
+
+Switches Alacritty's theme by copying a theme file under
+`~/.config/alacritty/`.
+
+### Example
+
+```bash
+x-change-alacritty-theme night
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-clean-vendordirs.md

@@ -0,0 +1,19 @@
+# x-clean-vendordirs
+
+Remove `vendor` and `node_modules` directories recursively.
+
+## Usage
+
+```bash
+x-clean-vendordirs [directory]
+```
+
+- `directory` – root directory to clean (default: current directory)
+
+## Example
+
+```bash
+x-clean-vendordirs ~/projects
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-compare-versions.py.md

@@ -0,0 +1,14 @@
+# x-compare-versions.py
+
+Compare version strings using Python's packaging library.
+
+## Usage
+
+```bash
+echo "1.2.3 >= 1.0.0" | x-compare-versions.py
+```
+
+The script reads comparison expressions from standard input and exits
+with status 0 if all comparisons are true.
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-dc.md

@@ -0,0 +1,19 @@
+# x-dc
+
+Create a directory if it does not exist.
+
+## Usage
+
+```bash
+x-dc <directory>
+```
+
+Set `VERBOSE=1` to see log messages.
+
+## Example
+
+```bash
+x-dc ~/tmp/mydir
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-dfm-docs-xterm-keybindings.md

@@ -0,0 +1,14 @@
+# x-dfm-docs-xterm-keybindings
+
+Generate `docs/tmux-keybindings.md` using tmux's key list.
+
+## Usage
+
+```bash
+x-dfm-docs-xterm-keybindings
+```
+
+No parameters are needed. The script writes the file under `docs/` and
+overwrites any existing version.
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-env-list.md

@@ -0,0 +1,21 @@
+# x-env-list
+
+Lists environment variables grouped by their prefix. Sensitive values
+are hidden by default.
+
+## Usage
+
+```bash
+x-env-list [options]
+```
+
+Use `--json` for machine readable output or specify
+`X_ENV_GROUPING` with a YAML file to override the default groups.
+
+### Example
+
+```bash
+X_ENV_GROUPING=~/env-groups.yaml x-env-list --json
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-foreach.md

@@ -0,0 +1,20 @@
+# x-foreach
+
+Run a command in each directory produced by another command.
+
+## Usage
+
+```bash
+x-foreach "<list-cmd>" "<cmd>"
+```
+
+- `list-cmd` – command that outputs directories
+- `cmd` – command to run inside each directory
+
+## Example
+
+```bash
+x-foreach "ls -d */" "git status"
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-gh-get-latest-release-targz.md

@@ -0,0 +1,19 @@
+# x-gh-get-latest-release-targz
+
+Fetch the tarball URL of the latest GitHub release or download it directly.
+
+## Usage
+
+```bash
+x-gh-get-latest-release-targz <owner/repo> [--get]
+```
+
+- `--get` – download and extract the tarball instead of printing the URL
+
+## Example
+
+```bash
+x-gh-get-latest-release-targz ivuorinen/dotfiles --get
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-gh-get-latest-version

@@ -97,7 +97,7 @@ Examples:
   # Use GitHub Enterprise API
   GITHUB_API_URL="https://github.example.com/api/v3/repos" $BIN ivuorinen/dotfiles
 EOF
-  exit 1
+  exit 0
 }
 
 # Check that required dependencies are installed

local/bin/x-git-largest-files.py.md

@@ -0,0 +1,21 @@
+# x-git-largest-files.py
+
+Lists the largest files in a git repository.
+
+```bash
+x-git-largest-files.py [options]
+```
+
+Options:
+
+- `-c NUM` – number of files to show (default: 10)
+- `--files-exceeding N` – list files larger than N KB
+- `-p` – sort by on-disk size instead of pack size
+
+## Example
+
+```bash
+x-git-largest-files.py -c 5
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-have.md

@@ -0,0 +1,18 @@
+# x-have
+
+Check if a command exists on the system. Exits with status 0 if found
+and 1 otherwise.
+
+## Usage
+
+```bash
+x-have <command>
+```
+
+### Example
+
+```bash
+x-have git && echo "git installed"
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-hr.md

@@ -0,0 +1,19 @@
+# x-hr
+
+Print a horizontal rule. Useful for visually separating log output.
+
+## Usage
+
+```bash
+x-hr [character]
+```
+
+If no character is given a red `-` is used.
+
+### Example
+
+```bash
+x-hr "="
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-ip.md

@@ -0,0 +1,19 @@
+# x-ip
+
+Fetch your public IP address using `curl`.
+
+## Usage
+
+```bash
+x-ip [curl-options]
+```
+
+Any arguments are passed directly to `curl`.
+
+### Example
+
+```bash
+x-ip -4
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-load-configs.md

@@ -0,0 +1,21 @@
+# x-load-configs
+
+Source shell configuration files for aliases and exports. Intended to
+be run after `dfm install` or when switching hosts.
+
+## Usage
+
+```bash
+x-load-configs
+```
+
+Set `VERBOSE=1` to print each file as it is sourced. Use `DEBUG=1` to
+enable tracing.
+
+### Example
+
+```bash
+VERBOSE=1 x-load-configs
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-localip.md

@@ -0,0 +1,25 @@
+# x-localip
+
+Display local IPv4 and IPv6 addresses with optional interface filtering.
+
+## Usage
+
+```bash
+x-localip [--ipv4] [--ipv6] [interface]
+```
+
+- `--ipv4` – show only IPv4 addresses
+- `--ipv6` – show only IPv6 addresses
+- `interface` – limit output to the named interface
+
+## Example
+
+```bash
+# Show all addresses
+x-localip
+
+# IPv4 for wlan0
+x-localip --ipv4 wlan0
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-mkd

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 #
 # Create a directory and cd into it
-# Usage: mkcd <dir>
+# Usage: x-mkd <dir>
 
 set -euo pipefail
 

local/bin/x-mkd.md

@@ -0,0 +1,19 @@
+# x-mkd
+
+Create a directory and immediately `cd` into it.
+
+## Usage
+
+```bash
+x-mkd <dir>
+```
+
+Set `VERBOSE=1` for status messages.
+
+## Example
+
+```bash
+x-mkd project && git init
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-multi-ping.md

@@ -0,0 +1,20 @@
+# x-multi-ping
+
+Multi-protocol ping helper supporting IPv4 and IPv6.
+
+## Usage
+
+```bash
+x-multi-ping [--loop] [--sleep=N] host1 host2...
+```
+
+- `--loop` – ping continuously
+- `--sleep` – seconds to wait between iterations
+
+## Example
+
+```bash
+x-multi-ping --loop --sleep=5 example.com
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-multi-ping.pl.md

@@ -0,0 +1,20 @@
+# x-multi-ping.pl
+
+Ping multiple hosts with IPv4/IPv6 support.
+
+## Usage
+
+```bash
+x-multi-ping.pl [--loop|--forever] [--sleep N] host1 host2 ...
+```
+
+`--loop` keeps pinging each host until interrupted. `--sleep` controls
+the delay between attempts.
+
+### Example
+
+```bash
+x-multi-ping.pl --loop --sleep 2 example.com 1.1.1.1
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-open-ports.md

@@ -0,0 +1,19 @@
+# x-open-ports
+
+List listening ports using `lsof` or `ss`.
+
+## Usage
+
+```bash
+x-open-ports [--json]
+```
+
+- `--json` – output as JSON instead of Markdown
+
+## Example
+
+```bash
+x-open-ports --json
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-path-append.md

@@ -0,0 +1,19 @@
+# x-path-append
+
+Append directories to the `PATH` variable without duplicates.
+
+## Usage
+
+```bash
+x-path-append <dir1> [dir2 ...]
+```
+
+Set `VERBOSE=1` for verbose logging.
+
+## Example
+
+```bash
+x-path-append /usr/local/sbin "$HOME/bin"
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-path-prepend.md

@@ -0,0 +1,19 @@
+# x-path-prepend
+
+Prepend directories to the `PATH` variable without duplicates.
+
+## Usage
+
+```bash
+x-path-prepend <dir1> [dir2 ...]
+```
+
+Set `VERBOSE=1` for verbose logging.
+
+## Example
+
+```bash
+x-path-prepend "$HOME/bin" /opt/tools
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-path-remove.md

@@ -0,0 +1,19 @@
+# x-path-remove
+
+Remove directories from the `PATH` variable.
+
+## Usage
+
+```bash
+x-path-remove <dir1> [dir2 ...]
+```
+
+Set `VERBOSE=1` for verbose logging.
+
+## Example
+
+```bash
+x-path-remove /usr/local/bin
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-path.md

@@ -0,0 +1,30 @@
+# x-path
+
+Manage entries in the `PATH` variable through subcommands.
+
+## Usage
+
+```bash
+x-path <command> <directory1> [directory2 ...]
+```
+
+### Commands
+
+- `append` / `a` – Append directories to `PATH`
+- `prepend` / `p` – Prepend directories to `PATH`
+- `remove` – Remove directories from `PATH`
+- `check` – Validate directories (default: all in `PATH`)
+
+Set `VERBOSE=1` for progress output.
+
+## Examples
+
+```bash
+# Prepend /opt/bin to PATH
+x-path prepend /opt/bin
+
+# Remove /usr/local/bin from PATH
+x-path remove /usr/local/bin
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-quota-usage.php.md

@@ -0,0 +1,14 @@
+# x-quota-usage.php
+
+Display filesystem quota usage in a human readable table.
+
+## Usage
+
+```bash
+x-quota-usage.php
+```
+
+Runs the `quota` command and formats the output. Requires PHP with the
+`shell_exec` function enabled.
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-record.md

@@ -0,0 +1,19 @@
+# x-record
+
+Interactive screen recording wrapper around `giph`.
+
+## Usage
+
+```bash
+x-record <gif|mkv|webm|mp4> <fullscreen|set>
+```
+
+The script asks for file type and area when omitted.
+
+## Example
+
+```bash
+x-record gif fullscreen
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-set-php-aliases.md

@@ -0,0 +1,14 @@
+# x-set-php-aliases
+
+---
+
+## Usage
+
+```bash
+source x-set-php-aliases
+```
+
+Generates shell aliases (`php80`, `php81` ...) for each Homebrew PHP
+installation. Caches the list under `$XDG_CACHE_HOME/x-set-php-aliases`.
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-sha256sum-matcher.md

@@ -0,0 +1,22 @@
+# x-sha256sum-matcher
+
+Compare two files by calculating their SHA256 checksums.
+
+## Usage
+
+```bash
+x-sha256sum-matcher [options] file1 file2
+```
+
+Options:
+
+- `-v` – verbose output
+- `-h, --help` – show help
+
+### Example
+
+```bash
+x-sha256sum-matcher original.iso download.iso
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-ssl-expiry-date.md

@@ -0,0 +1,22 @@
+# x-ssl-expiry-date
+
+Check the expiry date of an SSL certificate for one or more hosts.
+
+## Usage
+
+```bash
+x-ssl-expiry-date [-d] [-p PORT] host1 host2 ...
+```
+
+Options:
+
+- `-d` – show days left instead of the full date
+- `-p <port>` – use custom port (default: 443)
+
+### Example
+
+```bash
+x-ssl-expiry-date -d github.com
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-term-colors.md

@@ -0,0 +1,14 @@
+# x-term-colors
+
+Display a table of 24‑bit color codes for testing terminal color
+support.
+
+## Usage
+
+```bash
+x-term-colors
+```
+
+Pipe the output to `less -R` to view with color highlighting.
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-thumbgen.md

@@ -0,0 +1,26 @@
+# x-thumbgen
+
+Generate thumbnails using ImageMagick (magick) with MIME type filtering.
+
+## Usage
+
+```bash
+x-thumbgen [options] source_directory
+```
+
+Options:
+
+- `-o DIR` – output directory (default: same as source)
+- `-s STR` – suffix for thumbnails
+- `-h` – show help
+
+Environment variables like `THUMB_BACKGROUND` control the background
+color.
+
+### Example
+
+```bash
+THUMB_BACKGROUND=black x-thumbgen -o ~/thumbs ~/images
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-until-error.md

@@ -0,0 +1,20 @@
+# x-until-error
+
+Repeatedly execute a command until it returns a non-zero exit status.
+
+## Usage
+
+```bash
+x-until-error [--sleep SECONDS] command [args...]
+```
+
+Use `--sleep` to wait between runs. The command is executed at least
+once.
+
+### Example
+
+```bash
+x-until-error --sleep 2 ping -c1 example.com
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-until-success.md

@@ -0,0 +1,20 @@
+# x-until-success
+
+Repeat a command until it succeeds (exit status 0). The command is
+always executed at least once.
+
+## Usage
+
+```bash
+x-until-success [--sleep SECONDS] command [args...]
+```
+
+Use `--sleep` to control the delay between attempts.
+
+### Example
+
+```bash
+x-until-success --sleep 5 curl -I https://example.com
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-validate-sha256sum.sh.md

@@ -0,0 +1,14 @@
+# x-validate-sha256sum.sh
+
+This script contains a helper for sha256 validating your downloads
+
+## Usage
+
+```bash
+x-validate-sha256sum.sh file sha256sum
+```
+
+The script computes the SHA256 hash of `file` and compares it to the
+expected value. It exits non-zero if the sums differ.
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-welcome-banner.md

@@ -0,0 +1,13 @@
+# x-welcome-banner
+
+Print a colorful MOTD with greeting, system info and today's weather.
+
+## Usage
+
+```bash
+x-welcome-banner
+```
+
+Requires optional tools: `neofetch`, `figlet`, `lolcat` and `curl` for extra info.
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-when-down.md

@@ -0,0 +1,17 @@
+# x-when-down
+
+Wait until a host stops responding to ping, then run a command.
+
+## Usage
+
+```bash
+x-when-down <host> <command...>
+```
+
+## Example
+
+```bash
+x-when-down 1.2.3.4 echo "server down"
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->