Add documentation to the commands for the CLI

src/cli/autocomplete/scripts/bash.sh

@@ -1,7 +1,16 @@
-# bash completion for {{BIN_NAME}}
-# Add to ~/.bashrc:  eval "$({{BIN_NAME}} completions bash)"
+# ------------------------------------------------------------------------------
+# Bash completion template for {{BIN_NAME}}
+# ------------------------------------------------------------------------------
+# Installation:
+#   eval "$({{BIN_NAME}} completions bash)"
+#
+# This file is generated from a template. Placeholders (for example `{{OPTIONS}}`)
+# are replaced at build/runtime with concrete command data from the CLI.
+# ------------------------------------------------------------------------------
 
-# Find xo-complete in the same directory as xo-cli
+# Prefer a globally-installed helper, but fall back to a helper co-located with
+# the CLI binary. This lets completions work in both "installed via PATH" and
+# "single extracted directory" workflows.
 __xo_complete_bin=""
 if command -v xo-complete &>/dev/null; then
   __xo_complete_bin="xo-complete"
@@ -9,16 +18,28 @@ elif command -v {{BIN_NAME}} &>/dev/null; then
   __xo_complete_bin="$(dirname "$(command -v {{BIN_NAME}})")/xo-complete"
 fi
 
-# Wrapper to call xo-complete helper
+# @description
+# Calls the dynamic completion helper and suppresses helper stderr so the shell
+# completion menu stays clean even when the helper is unavailable or errors.
+# @param "$@" Arguments forwarded to xo-complete.
 __xo_complete() {
   [[ -n "${__xo_complete_bin}" ]] && "${__xo_complete_bin}" "$@" 2>/dev/null
 }
 
+# @description
+# Main completion dispatcher invoked by bash's `complete -F`.
+# It determines context (command/subcommand/argument position) and then mixes:
+# - static completions (known command words)
+# - dynamic completions (resolved by xo-complete)
+# - filesystem completions (when a subcommand expects file paths)
 _{{FUNC_NAME}}_completions() {
   local cur prev words cword
+  # Populates `cur`, `prev`, `words`, and `cword`.
+  # `_init_completion` is provided by bash-completion.
   _init_completion || return
 
-  # Handle -m/--mnemonic-file argument (previous word was -m)
+  # If the previous token is `-m/--mnemonic-file`, this argument expects a
+  # mnemonic file alias/path. Ask the helper for mnemonic suggestions.
   if [[ "${prev}" == "-m" || "${prev}" == "--mnemonic-file" ]]; then
     local mnemonics
     mnemonics=$(__xo_complete mnemonics "${cur}")
@@ -30,13 +51,14 @@ _{{FUNC_NAME}}_completions() {
     fi
   fi
 
-  # If the current word starts with "-", offer option flags
+  # Option context: show global options when the current token starts with `-`.
   if [[ "${cur}" == -* ]]; then
     COMPREPLY=($(compgen -W "{{OPTIONS}}" -- "${cur}"))
     return 0
   fi
 
-  # Find the command and subcommand positions
+  # Parse command/subcommand from non-option tokens before the current cursor.
+  # We track indices so argument-position logic can be computed later.
   local cmd="" subcmd="" cmd_idx=0 subcmd_idx=0
   for ((i=1; i < cword; i++)); do
     if [[ "${words[i]}" != -* ]]; then
@@ -51,13 +73,13 @@ _{{FUNC_NAME}}_completions() {
     fi
   done
 
-  # No command yet — offer the top-level commands
+  # No command selected yet: complete top-level commands.
   if [[ -z "${cmd}" ]]; then
     COMPREPLY=($(compgen -W "{{COMMANDS}}" -- "${cur}"))
     return 0
   fi
 
-  # Handle each command's completion
+  # Command-specific completion rules.
   case "${cmd}" in
     mnemonic)
       if [[ -z "${subcmd}" ]]; then
@@ -69,7 +91,9 @@ _{{FUNC_NAME}}_completions() {
       if [[ -z "${subcmd}" ]]; then
         COMPREPLY=($(compgen -W "{{TEMPLATE_SUBS}}" -- "${cur}"))
       elif [[ "${subcmd}" == "list" || "${subcmd}" == "inspect" ]]; then
-        # template list/inspect <category> <template> [field] - category first, then template, then field
+        # template list/inspect <category> <template> [field]
+        # Position is computed relative to the subcommand token:
+        #   1 => category, 2 => template, 3 => field (inspect only)
         local pos=$((cword - subcmd_idx))
         if [[ $pos -eq 1 ]]; then
           COMPREPLY=($(compgen -W "action transaction output lockingscript variable" -- "${cur}"))
@@ -82,7 +106,7 @@ _{{FUNC_NAME}}_completions() {
             done <<< "${templates}"
           fi
         elif [[ $pos -eq 3 && "${subcmd}" == "inspect" ]]; then
-          # Get the category and template from previous args
+          # Field names depend on both selected category and template.
           local category="${words[subcmd_idx + 1]}"
           local template_arg="${words[subcmd_idx + 2]}"
           local fields
@@ -94,7 +118,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>
+        # We only complete the first positional argument (template) here.
         local pos=$((cword - subcmd_idx))
         if [[ $pos -eq 1 ]]; then
           local templates
@@ -114,7 +139,8 @@ _{{FUNC_NAME}}_completions() {
       else
         case "${subcmd}" in
           create)
-            # invitation create <template> <action> - offer templates then actions
+            # invitation create <template> <action>
+            # The available actions depend on the selected template.
             local pos=$((cword - subcmd_idx))
             if [[ $pos -eq 1 ]]; then
               local templates
@@ -136,7 +162,7 @@ _{{FUNC_NAME}}_completions() {
             fi
             ;;
           append|sign|broadcast|requirements|inspect)
-            # These take an invitation ID
+            # These subcommands expect an invitation identifier as first arg.
             local pos=$((cword - subcmd_idx))
             if [[ $pos -eq 1 ]]; then
               local invitations
@@ -149,7 +175,7 @@ _{{FUNC_NAME}}_completions() {
             fi
             ;;
           import)
-            # import takes a file path - use default file completion
+            # File import path: delegate to bash's built-in file completion.
             COMPREPLY=($(compgen -f -- "${cur}"))
             ;;
         esac
@@ -160,7 +186,8 @@ _{{FUNC_NAME}}_completions() {
       if [[ -z "${subcmd}" ]]; then
         COMPREPLY=($(compgen -W "{{RESOURCE_SUBS}}" -- "${cur}"))
       elif [[ "${subcmd}" == "unreserve" ]]; then
-        # resource unreserve <txhash:vout> - offer resources
+        # resource unreserve <txhash:vout>
+        # Suggest known reserved outpoints from the helper.
         local pos=$((cword - subcmd_idx))
         if [[ $pos -eq 1 ]]; then
           local resources
@@ -175,7 +202,8 @@ _{{FUNC_NAME}}_completions() {
       ;;
 
     receive)
-      # receive <template> [output] - offer templates
+      # receive <template> [output]
+      # Template is the first positional argument after `receive`.
       local pos=$((cword - cmd_idx))
       if [[ $pos -eq 1 ]]; then
         local templates
@@ -189,6 +217,7 @@ _{{FUNC_NAME}}_completions() {
       ;;
 
     completions)
+      # Shell target for generating completion scripts.
       if [[ -z "${subcmd}" ]]; then
         COMPREPLY=($(compgen -W "bash zsh fish" -- "${cur}"))
       fi
@@ -196,4 +225,5 @@ _{{FUNC_NAME}}_completions() {
   esac
 }
 
+# Register the completion function for the CLI binary.
 complete -F _{{FUNC_NAME}}_completions {{BIN_NAME}}