feat(bin): add x-visit-folders script for bulk zoxide registration (#294)

* feat(bin): add x-visit-folders script for bulk zoxide registration

* fix(bin): fix x-visit-folders usage exit code, no-op fallback, and count increment

- usage() now accepts optional exit code; --help exits 0
- Remove no-op subshell cd fallback in visit_dir(), just log failure
- Replace ((count++)) with count=$((count + 1)) to avoid set -e trap

local/bin/x-visit-folders

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+#
+# Register level-1 subdirectories with zoxide so they appear
+# in `z` completions.
+# Usage: x-visit-folders [options] [directory]
+#
+# Example: x-visit-folders ~/Code/ivuorinen
+#
+# Copyright (c) 2026 Ismo Vuorinen. All Rights Reserved.
+# Licensed under the MIT license.
+#
+# @description Register level-1 subdirectories with zoxide
+
+set -euo pipefail
+
+# Enable verbosity with VERBOSE=1
+VERBOSE="${VERBOSE:-0}"
+DRY_RUN=0
+
+# Function to print usage information
+usage()
+{
+  echo "Usage: $0 [options] [directory]"
+  echo ""
+  echo "Options:"
+  echo "  -h, --help     Show this help message"
+  echo "  -v, --verbose  Print each directory as it is visited"
+  echo "  -n, --dry-run  List directories without adding them"
+  local code="${1:-1}"
+  exit "$code"
+}
+
+# Function to print messages if VERBOSE is enabled
+# $1 - message (string)
+msg()
+{
+  [[ "$VERBOSE" -eq 1 ]] && echo "$1"
+}
+
+# Function to print error messages and exit
+# $1 - error message (string)
+msg_err()
+{
+  echo "(!) ERROR: $1" >&2
+  exit 1
+}
+
+# Function to register a directory with zoxide
+# $1 - directory path (string)
+visit_dir()
+{
+  if zoxide add "$1" 2> /dev/null; then
+    msg "Added: $1"
+  else
+    msg "zoxide add failed for: $1"
+  fi
+}
+
+# Main function
+main()
+{
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      -h | --help) usage 0 ;;
+      -v | --verbose) VERBOSE=1 ;;
+      -n | --dry-run) DRY_RUN=1 ;;
+      -*)
+        msg_err "Unknown option: $1"
+        ;;
+      *)
+        break
+        ;;
+    esac
+    shift
+  done
+
+  local target="${1:-.}"
+
+  if [[ ! -d "$target" ]]; then
+    msg_err "Not a directory: $target"
+  fi
+
+  target="$(cd "$target" && pwd)"
+
+  local count=0
+  for dir in "$target"/*/; do
+    [[ -d "$dir" ]] || continue
+    local name
+    name="$(basename "$dir")"
+    [[ "$name" == .* ]] && continue
+
+    if [[ "$DRY_RUN" -eq 1 ]]; then
+      echo "(dry-run) $dir"
+    else
+      visit_dir "$dir"
+    fi
+    count=$((count + 1))
+  done
+
+  echo "Visited $count directories."
+}
+
+main "$@"

local/bin/x-visit-folders.md

@@ -0,0 +1,23 @@
+# x-visit-folders
+
+Register level-1 subdirectories with zoxide so they appear in
+`z` completions.
+
+## Usage
+
+```bash
+x-visit-folders [options] [directory]
+```
+
+- `directory` – target directory (defaults to current directory)
+- `-n`, `--dry-run` – list directories without adding them
+- `-v`, `--verbose` – print each directory as it is visited
+- `-h`, `--help` – show usage information
+
+## Example
+
+```bash
+x-visit-folders ~/Code/ivuorinen
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->