Add comprehensive inline metadata documentation to all BackTunnel scripts

scripts/backtunnel-open-term

@@ -1,13 +1,44 @@
 #!/usr/bin/env bash
-# Open a command in the user's available terminal emulator, with logging.
-# Usage: backtunnel-open-term <cmd> [args...]
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (c) 2025 LUXIM d.o.o., Slovenia
+# Author: Matjaž Mozetič
+#
+# Name: backtunnel-open-term
+# Summary: Open a command in the user's available terminal emulator, with logging and simple rotation.
+# Description:
+#   Detects an installed terminal emulator (preferring Konsole on KDE sessions), opens it,
+#   and executes the provided command with arguments. Logs session metadata and output to
+#   ${XDG_STATE_HOME:-$HOME/.local/state}/backtunnel/servicemenu.<timestamp>.log, keeping the
+#   last 10 logs with a portable rotation routine.
+#
+# Usage:
+#   backtunnel-open-term <cmd> [args...]
+#
+# Examples:
+#   backtunnel-open-term backtunnel-access-tui "/path/to/dir"
+#   backtunnel-open-term bash -lc 'echo Hello'
+#
+# Dependencies:
+#   - bash
+#   - A terminal emulator (one of: konsole, kitty, alacritty, gnome-terminal, kgx, tilix, xfce4-terminal, xterm)
+#   - stat, sort, cut, date (coreutils-compatible)
+#
+# Exit codes:
+#   0  started successfully (or backgrounded if no terminal is available)
+#   1+ invalid usage or failures during setup/execution
+#
+# Notes:
+#   - If no terminal emulator is found, the command is started in the background via nohup
+#     and the log path is printed.
+#   - Uses exec for supported terminals to replace the current process; otherwise prints info then exits.
 set -euo pipefail
-
+# ... existing code ...
 LOG_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/backtunnel"
 [[ -d "$LOG_DIR" ]] || mkdir -p "$LOG_DIR"
 LOG_FILE="${LOG_DIR}/servicemenu.$(date +%Y%m%d-%H%M%S).log"
 
 # Simple rotation: keep the last 10 files (portable, avoids SC2207 and xargs -r)
+# Purpose: remove older log files while remaining compatible across GNU/BSD userlands.
 shopt -s nullglob
 logs=( "$LOG_DIR"/servicemenu.*.log )
 if (( ${#logs[@]} > 10 )); then
@@ -40,7 +71,9 @@ cmd=( "$@" )
   echo "Env:  BACKTUNNEL_DEBUG=${BACKTUNNEL_DEBUG:-}  SHELL=${SHELL:-}  DISPLAY=${DISPLAY:-}"
   echo
 
-  # Prefer Konsole on KDE sessions; otherwise probe common terminals
+  # detect_term: choose a terminal emulator to launch the command
+  # Output: prints the chosen terminal name or empty string if none found.
+  # Prefers Konsole when KDE session is detected.
   detect_term() {
     if [[ -n "${KDE_FULL_SESSION:-}" ]] && command -v konsole >/dev/null 2>&1; then
       echo "konsole"; return
@@ -50,7 +83,7 @@ cmd=( "$@" )
     done
     echo ""  # none
   }
-
+  # ... existing code ...
   term="$(detect_term)"
   echo "Chosen terminal: ${term:-<none>}"; echo