Add documentation to the commands for the CLI

src/cli/autocomplete/scripts/zsh.zsh

@@ -1,7 +1,15 @@
-# zsh completion for {{BIN_NAME}}
-# Add to ~/.zshrc:  eval "$({{BIN_NAME}} completions zsh)"
+# ------------------------------------------------------------------------------
+# Zsh completion template for {{BIN_NAME}}
+# ------------------------------------------------------------------------------
+# Installation:
+#   eval "$({{BIN_NAME}} completions zsh)"
+#
+# This file is generated from a template. Placeholders (for example
+# `{{MNEMONIC_SUBS}}`) are replaced with concrete command values.
+# ------------------------------------------------------------------------------
 
-# Find xo-complete in the same directory as xo-cli
+# Prefer a helper on PATH; otherwise fall back to helper next to the CLI binary.
+# This keeps dynamic completion functional in both installed and portable layouts.
 __xo_complete_bin=""
 if (( $+commands[xo-complete] )); then
   __xo_complete_bin="xo-complete"
@@ -9,16 +17,25 @@ elif (( $+commands[{{BIN_NAME}}] )); then
   __xo_complete_bin="${commands[{{BIN_NAME}}]:h}/xo-complete"
 fi
 
-# Wrapper to call xo-complete helper
+# @description
+# Calls the dynamic helper while silencing helper stderr to avoid noisy
+# completion menus if helper lookup fails.
+# @param "$@" Arguments forwarded to xo-complete.
 __xo_complete() {
   [[ -n "${__xo_complete_bin}" ]] && "${__xo_complete_bin}" "$@" 2>/dev/null
 }
 
+# @description
+# Main zsh completion dispatcher registered via `compdef`.
+# It resolves command context from `$words`/`$CURRENT` and serves:
+# - static command words via `compadd`
+# - dynamic values from `xo-complete`
+# - filesystem completions where file paths are expected
 _{{FUNC_NAME}}_completions() {
   local -a commands
   commands=({{COMMANDS}})
 
-  # Handle -m/--mnemonic-file argument (previous word was -m)
+  # If previous token is `-m/--mnemonic-file`, complete mnemonic sources.
   if [[ "${words[CURRENT-1]}" == "-m" || "${words[CURRENT-1]}" == "--mnemonic-file" ]]; then
     local mnemonics
     mnemonics=("${(@f)$(__xo_complete mnemonics "${words[CURRENT]}")}")
@@ -28,13 +45,14 @@ _{{FUNC_NAME}}_completions() {
     fi
   fi
 
-  # If typing an option flag, complete options
+  # Option context: if current token starts with `-`, complete known options.
   if [[ "${words[${CURRENT}]}" == -* ]]; then
     compadd -- {{OPTIONS}}
     return
   fi
 
-  # Find the command and subcommand
+  # Find first and second non-option tokens before the cursor.
+  # `cmd_idx` and `subcmd_idx` are used for positional argument calculations.
   local cmd="" subcmd="" cmd_idx=0 subcmd_idx=0
   for ((i=2; i < CURRENT; i++)); do
     if [[ "${words[i]}" != -* ]]; then
@@ -49,13 +67,13 @@ _{{FUNC_NAME}}_completions() {
     fi
   done
 
-  # No command yet — offer top-level commands
+  # No command token yet: offer top-level commands.
   if [[ -z "${cmd}" ]]; then
     compadd -- ${commands[@]}
     return
   fi
 
-  # Handle each command's completion
+  # Command-specific completion behavior.
   case "${cmd}" in
     mnemonic)
       if [[ -z "${subcmd}" ]]; then
@@ -67,7 +85,9 @@ _{{FUNC_NAME}}_completions() {
       if [[ -z "${subcmd}" ]]; then
         compadd -- {{TEMPLATE_SUBS}}
       elif [[ "${subcmd}" == "list" || "${subcmd}" == "inspect" ]]; then
-        # template list/inspect <category> <template> [field] - category first, then template, then field
+        # template list/inspect <category> <template> [field]
+        # Relative positions from subcommand:
+        #   1 => category, 2 => template, 3 => field (inspect only)
         local pos=$((CURRENT - subcmd_idx))
         if [[ $pos -eq 1 ]]; then
           compadd -- action transaction output lockingscript variable
@@ -78,7 +98,7 @@ _{{FUNC_NAME}}_completions() {
             compadd -- "${templates[@]}"
           fi
         elif [[ $pos -eq 3 && "${subcmd}" == "inspect" ]]; then
-          # Get the category and template from previous args
+          # Field suggestions depend on selected category and template.
           local category="${words[subcmd_idx + 1]}"
           local template_arg="${words[subcmd_idx + 2]}"
           local fields
@@ -88,7 +108,8 @@ _{{FUNC_NAME}}_completions() {
           fi
         fi
       elif [[ "${subcmd}" == "set-default" ]]; then
-        # template set-default <template> <output> <role> - template first
+        # template set-default <template> <output> <role>
+        # First positional argument is template name.
         local pos=$((CURRENT - subcmd_idx))
         if [[ $pos -eq 1 ]]; then
           local templates
@@ -106,6 +127,8 @@ _{{FUNC_NAME}}_completions() {
       else
         case "${subcmd}" in
           create)
+            # invitation create <template> <action>
+            # Action list is template-specific.
             local pos=$((CURRENT - subcmd_idx))
             if [[ $pos -eq 1 ]]; then
               local templates
@@ -123,6 +146,7 @@ _{{FUNC_NAME}}_completions() {
             fi
             ;;
           append|sign|broadcast|requirements|inspect)
+            # These subcommands take invitation ID as first argument.
             local pos=$((CURRENT - subcmd_idx))
             if [[ $pos -eq 1 ]]; then
               local invitations
@@ -133,6 +157,7 @@ _{{FUNC_NAME}}_completions() {
             fi
             ;;
           import)
+            # invitation import <path>: delegate to zsh file completion.
             _files
             ;;
         esac
@@ -143,6 +168,7 @@ _{{FUNC_NAME}}_completions() {
       if [[ -z "${subcmd}" ]]; then
         compadd -- {{RESOURCE_SUBS}}
       elif [[ "${subcmd}" == "unreserve" ]]; then
+        # resource unreserve <txhash:vout>
         local pos=$((CURRENT - subcmd_idx))
         if [[ $pos -eq 1 ]]; then
           local resources
@@ -155,6 +181,7 @@ _{{FUNC_NAME}}_completions() {
       ;;
 
     receive)
+      # receive <template> [output]
       local pos=$((CURRENT - cmd_idx))
       if [[ $pos -eq 1 ]]; then
         local templates
@@ -166,6 +193,7 @@ _{{FUNC_NAME}}_completions() {
       ;;
 
     completions)
+      # Shell target for completion generation.
       if [[ -z "${subcmd}" ]]; then
         compadd -- bash zsh fish
       fi
@@ -173,4 +201,5 @@ _{{FUNC_NAME}}_completions() {
   esac
 }
 
+# Register completion function for the executable name.
 compdef _{{FUNC_NAME}}_completions {{BIN_NAME}}