Add better doc

install-scripts/install-safe-chain.ps1

@@ -8,6 +8,8 @@ param(
     [string]$InstallDir
 )
 
+# Validates and normalizes the requested install directory.
+# Rejects non-absolute, root, PATH-like, and traversal-containing paths.
 function Test-InstallDir {
     param([string]$Dir)
 
@@ -137,6 +139,8 @@ function Get-Architecture {
     }
 }
 
+# Emits the deprecation warning for SAFE_CHAIN_VERSION and prints the version-pinned install command.
+# Returns immediately when no version was provided through the environment.
 function Write-VersionDeprecationWarning {
     if ([string]::IsNullOrWhiteSpace($env:SAFE_CHAIN_VERSION)) {
         return
@@ -154,12 +158,16 @@ function Write-VersionDeprecationWarning {
     Write-Warn ""
 }
 
+# Builds the Windows release binary filename for the detected architecture.
+# Centralizes binary name generation for the download step.
 function Get-BinaryName {
     param([string]$Architecture)
 
     return "safe-chain-win-$Architecture.exe"
 }
 
+# Runs safe-chain setup or setup-ci after the binary is installed.
+# Temporarily appends the install directory to PATH and downgrades setup failures to warnings.
 function Invoke-SafeChainSetup {
     param(
         [string]$BinaryPath,

install-scripts/install-safe-chain.sh

@@ -6,6 +6,8 @@
 
 set -e  # Exit on error
 
+# Validates a user-provided install dir and exits on unsafe values.
+# Rejects relative paths, root paths, PATH separators, and traversal segments.
 validate_install_dir() {
     dir="$1"
 
@@ -168,6 +170,8 @@ download() {
     fi
 }
 
+# Prints the deprecation warning for SAFE_CHAIN_VERSION and the replacement install command.
+# Returns immediately when no version was pinned through the environment.
 warn_deprecated_version_env() {
     if [ -z "$SAFE_CHAIN_VERSION" ]; then
         return
@@ -185,6 +189,8 @@ warn_deprecated_version_env() {
     warn ""
 }
 
+# Ensures VERSION is populated before installation continues.
+# Fetches the latest release only when no explicit version was provided.
 ensure_version() {
     if [ -n "$VERSION" ]; then
         return
@@ -194,6 +200,7 @@ ensure_version() {
     VERSION=$(fetch_latest_version)
 }
 
+# Returns the release binary filename for the detected OS and architecture.
 get_binary_name() {
     os="$1"
     arch="$2"
@@ -205,6 +212,8 @@ get_binary_name() {
     fi
 }
 
+# Returns the final installation path for the downloaded safe-chain binary.
+# Uses INSTALL_DIR and the platform-specific executable name.
 get_final_binary_path() {
     os="$1"
 

install-scripts/uninstall-safe-chain.ps1

@@ -22,6 +22,8 @@ function Write-Error-Custom {
     exit 1
 }
 
+# Derives the safe-chain base install directory from a resolved binary path.
+# Rejects wrapper scripts and paths that do not match the packaged bin layout.
 function Get-InstallDirFromBinaryPath {
     param([string]$BinaryPath)
 
@@ -53,10 +55,14 @@ function Get-InstallDirFromBinaryPath {
     return (Split-Path -Parent $binDir)
 }
 
+# Returns the first safe-chain command found on PATH, if any.
+# Used as the starting point for install-dir discovery.
 function Get-SafeChainCommand {
     return Get-Command safe-chain -ErrorAction SilentlyContinue | Select-Object -First 1
 }
 
+# Returns the safe-chain command path only when it points to a valid packaged binary install.
+# Prevents teardown from invoking arbitrary wrappers or scripts from PATH.
 function Get-ValidatedSafeChainCommandPath {
     $command = Get-SafeChainCommand
     if (-not $command -or [string]::IsNullOrWhiteSpace($command.Path)) {
@@ -71,6 +77,8 @@ function Get-ValidatedSafeChainCommandPath {
     return $command.Path
 }
 
+# Invokes the validated safe-chain binary with get-install-dir and returns the reported base directory.
+# Safely returns $null when the command is unavailable or the lookup fails.
 function Get-ReportedInstallDir {
     $safeChainPath = Get-ValidatedSafeChainCommandPath
     if (-not $safeChainPath) {
@@ -93,6 +101,8 @@ function Get-ReportedInstallDir {
     return $null
 }
 
+# Determines the safe-chain base install directory for uninstall.
+# Prefers the binary-reported location, then derives it from PATH, then falls back to the default home-dir layout.
 function Get-SafeChainInstallDir {
     $reportedInstallDir = Get-ReportedInstallDir
     if ($reportedInstallDir) {
@@ -110,6 +120,8 @@ function Get-SafeChainInstallDir {
     return (Join-Path $HomeDir ".safe-chain")
 }
 
+# Finds the installed safe-chain binary inside the resolved install directory.
+# Falls back to a validated safe-chain command when the expected file is missing.
 function Find-SafeChainBinary {
     param([string]$DotSafeChain)
 
@@ -127,6 +139,8 @@ function Find-SafeChainBinary {
     return Get-ValidatedSafeChainCommandPath
 }
 
+# Runs safe-chain teardown before removing the installation directory.
+# Converts teardown failures into warnings so uninstall can still complete.
 function Invoke-SafeChainTeardown {
     param([string]$SafeChainPath)
 

install-scripts/uninstall-safe-chain.sh

@@ -33,6 +33,8 @@ command_exists() {
     command -v "$1" >/dev/null 2>&1
 }
 
+# Resolves a path to its canonical filesystem location when possible.
+# Follows symlinks so binary validation can inspect the real installed path.
 resolve_path() {
     target="$1"
 
@@ -60,6 +62,8 @@ resolve_path() {
     fi
 }
 
+# Derives the safe-chain base install directory from a packaged binary path.
+# Rejects wrapper scripts and paths that do not match the expected bin layout.
 derive_install_dir_from_binary() {
     binary_path="$1"
 
@@ -86,6 +90,8 @@ derive_install_dir_from_binary() {
     dirname "$binary_dir"
 }
 
+# Determines the installed safe-chain base directory for uninstall.
+# Prefers the binary-reported location, then infers it from PATH, then falls back to ~/.safe-chain.
 get_install_dir() {
     reported_install_dir=$(get_reported_install_dir)
     if [ -n "$reported_install_dir" ]; then
@@ -103,6 +109,8 @@ get_install_dir() {
     printf '%s\n' "${HOME}/.safe-chain"
 }
 
+# Returns the current safe-chain command path from PATH.
+# Fails when safe-chain is not currently resolvable.
 get_safe_chain_command_path() {
     if ! command_exists safe-chain; then
         return 1
@@ -111,6 +119,8 @@ get_safe_chain_command_path() {
     command -v safe-chain
 }
 
+# Returns the safe-chain command path only when it resolves to a valid packaged binary install.
+# Prevents the uninstaller from invoking arbitrary PATH entries.
 get_validated_safe_chain_command_path() {
     command_path=$(get_safe_chain_command_path || true)
     if [ -z "$command_path" ]; then
@@ -125,6 +135,8 @@ get_validated_safe_chain_command_path() {
     printf '%s\n' "$command_path"
 }
 
+# Asks the validated safe-chain binary for its install directory via get-install-dir.
+# Returns nothing if the command is unavailable or the lookup fails.
 get_reported_install_dir() {
     safe_chain_path=$(get_validated_safe_chain_command_path || true)
     if [ -z "$safe_chain_path" ]; then
@@ -140,6 +152,8 @@ get_reported_install_dir() {
     return 1
 }
 
+# Locates the installed safe-chain binary to use for teardown.
+# Checks the discovered install dir first, then falls back to a validated PATH entry.
 find_installed_safe_chain_binary() {
     dot_safe_chain="$1"
 
@@ -158,6 +172,8 @@ find_installed_safe_chain_binary() {
     return 1
 }
 
+# Runs safe-chain teardown before removing files.
+# Continues with uninstall even if teardown is unavailable or fails.
 run_safe_chain_teardown() {
     safe_chain_command="$1"