@sebastienrousseau/dotfiles 0.2.499 → 0.2.501

package/scripts/dot/lib/utils.sh

@@ -0,0 +1,377 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# Sourced by scripts/dot/commands/*.sh and dot_local/bin/executable_dot; inherits set -euo pipefail.
+# Dotfiles CLI Utilities
+# Shared functions for dot command modules
+
+# Re-source guard: cheap short-circuit when sourced from multiple modules.
+[[ "${_DOT_LIB_UTILS_LOADED:-0}" == "1" ]] && return 0
+_DOT_LIB_UTILS_LOADED=1
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=ui.sh
+source "$SCRIPT_DIR/ui.sh"
+# shellcheck source=platform.sh
+source "$SCRIPT_DIR/platform.sh"
+
+_DOT_SOURCE_DIR_CACHE=""
+
+## resolve_source_dir — Locate the dotfiles source tree.
+## Checks (in order): relative to this script, $CHEZMOI_SOURCE_DIR,
+## ~/.dotfiles, ~/.local/share/chezmoi. Caches the result for the process.
+## Prints the absolute path (or empty string if not found). Exit: always 0.
+resolve_source_dir() {
+  if [[ -n "${_DOT_SOURCE_DIR_CACHE:-}" ]] && [[ -d "$_DOT_SOURCE_DIR_CACHE" ]]; then
+    printf "%s\n" "$_DOT_SOURCE_DIR_CACHE"
+    return
+  fi
+
+  local dir=""
+  local repo_candidate=""
+
+  if repo_candidate="$(cd "$SCRIPT_DIR/../../.." && pwd 2>/dev/null)"; then
+    :
+  else
+    repo_candidate=""
+  fi
+  if [[ -n "$repo_candidate" && -f "$repo_candidate/scripts/dot/lib/ui.sh" ]]; then
+    dir="$repo_candidate"
+  elif [ -n "${CHEZMOI_SOURCE_DIR:-}" ] && [ -d "$CHEZMOI_SOURCE_DIR" ]; then
+    dir="$CHEZMOI_SOURCE_DIR"
+  elif [ -d "$HOME/.dotfiles" ]; then
+    dir="$HOME/.dotfiles"
+  elif [ -d "$HOME/.local/share/chezmoi" ]; then
+    dir="$HOME/.local/share/chezmoi"
+  fi
+
+  if [ -n "$dir" ]; then
+    # Resolve symlinks for consistent path handling
+    if command -v realpath >/dev/null 2>&1; then
+      dir="$(realpath "$dir")"
+    elif command -v readlink >/dev/null 2>&1; then
+      dir="$(readlink -f "$dir" 2>/dev/null || echo "$dir")"
+    fi
+    _DOT_SOURCE_DIR_CACHE="$dir"
+    printf "%s\n" "$dir"
+  else
+    printf "%s\n" ""
+  fi
+}
+
+## run_script — Resolve source dir, find a script, exec it (never returns).
+## Usage: run_script <relative-script-path> <not-found-label> [args...]
+## Exit: 1 if source dir or script not found; otherwise execs into the script.
+run_script() {
+  local script_rel="$1"
+  local label="$2"
+  shift 2
+  local src_dir
+  src_dir="$(resolve_source_dir)"
+  if [ -z "$src_dir" ]; then
+    echo "Dotfiles source not found." >&2
+    exit 1
+  fi
+  if [ -f "$src_dir/$script_rel" ]; then
+    exec bash "$src_dir/$script_rel" "$@"
+  else
+    echo "$label not found." >&2
+    exit 1
+  fi
+}
+
+## require_source_dir — Print source dir path or exit 1 if not found.
+require_source_dir() {
+  local src_dir
+  src_dir="$(resolve_source_dir)"
+  if [ -z "$src_dir" ]; then
+    echo "Dotfiles source not found." >&2
+    exit 1
+  fi
+  echo "$src_dir"
+}
+
+## has_command <name> — Return 0 if <name> is on PATH, 1 otherwise.
+has_command() {
+  command -v "$1" >/dev/null 2>&1
+}
+
+## validate_name <name> [label] — Die if name contains unsafe characters.
+## Allowed: [a-zA-Z0-9._-]. This prevents shell injection when names appear
+## in paths or eval contexts. Exit: 0 if valid, calls die() if invalid.
+validate_name() {
+  local name="$1" label="${2:-name}"
+  if [[ ! "$name" =~ ^[a-zA-Z0-9._-]+$ ]]; then
+    die "Invalid $label: $name (only alphanumeric, dash, underscore, dot allowed)"
+  fi
+}
+
+## validate_xdg_path <var_name> <path> — Warn and return 1 if path is not absolute.
+validate_xdg_path() {
+  local var_name="$1" path="$2"
+  if [[ -n "$path" ]] && [[ "$path" != /* ]]; then
+    ui_warn "$var_name" "Not an absolute path: $path (ignoring, using default)"
+    return 1
+  fi
+  return 0
+}
+
+## die <message> [code] — Print error to stderr and exit (default code 1).
+die() {
+  ui_err "$1" >&2
+  exit "${2:-1}"
+}
+
+# Print warning message
+warn() {
+  ui_warn "$1" >&2
+}
+
+# Print info message
+info() {
+  ui_info "$1"
+}
+
+# Print the dot logo once per process for interactive sessions.
+ui_logo_once() {
+  local title="${1:-Dot}"
+  ui_init
+  if [[ "${DOTFILES_SHOW_LOGO:-1}" != "1" ]]; then
+    return
+  fi
+  if [[ ! -t 1 ]]; then
+    return
+  fi
+  if [[ "${DOTFILES_LOGO_PRINTED:-0}" = "1" ]]; then
+    return
+  fi
+  ui_product_banner "$title"
+}
+
+dotfiles_version() {
+  local src_dir version=""
+  src_dir="$(resolve_source_dir)"
+
+  if [[ -n "$src_dir" ]] && [[ -f "$src_dir/package.json" ]]; then
+    version="$(sed -n 's/^[[:space:]]*"version"[[:space:]]*:[[:space:]]*"\([0-9][0-9.]*\)".*/\1/p' "$src_dir/package.json" | head -1)"
+  fi
+
+  if [[ -z "$version" ]] && [[ -n "${DOTFILES_VERSION:-}" ]]; then
+    version="$DOTFILES_VERSION"
+  fi
+
+  if [[ -z "$version" ]]; then
+    version="unknown"
+  fi
+
+  printf "%s\n" "$version"
+}
+
+dot_command_summary() {
+  case "${1:-}" in
+    apply | sync)
+      echo "Apply dotfiles changes (sync is an alias for apply)."
+      ;;
+    update)
+      echo "Pull latest changes from remote, then apply."
+      ;;
+    add)
+      echo "Add a file into chezmoi source management."
+      ;;
+    diff)
+      echo "Show pending managed-file differences."
+      ;;
+    status)
+      echo "Show current configuration drift status."
+      ;;
+    remove)
+      echo "Safely remove a managed file from source."
+      ;;
+    cd)
+      echo "Print the dotfiles source directory path."
+      ;;
+    edit)
+      echo "Open dotfiles source in your editor."
+      ;;
+    doctor)
+      echo "Deep audit: tools, paths, portability, AI analysis."
+      ;;
+    heal)
+      echo "Auto-repair broken symlinks, missing tools, and drift."
+      ;;
+    health | health-check)
+      echo "Dashboard with health score, checks, and auto-fix (--fix)."
+      ;;
+    security-score)
+      echo "Calculate and print security posture score."
+      ;;
+    scorecard)
+      echo "Show unified health, security, and performance scorecard."
+      ;;
+    perf)
+      echo "Profile shell startup performance (3-run average)."
+      ;;
+    conflicts)
+      echo "Report alias and command conflicts."
+      ;;
+    locks)
+      echo "Show version locks for key tools."
+      ;;
+    snapshot)
+      echo "Capture a baseline system snapshot."
+      ;;
+    rollback)
+      echo "Rollback dotfiles state to a prior point."
+      ;;
+    restore)
+      echo "Restore files from backup or git reference."
+      ;;
+    drift)
+      echo "Display detailed drift information."
+      ;;
+    history)
+      echo "Analyze shell command history."
+      ;;
+    benchmark)
+      echo "Measure shell startup performance."
+      ;;
+    verify)
+      echo "Run post-merge verification checks."
+      ;;
+    tools)
+      echo "Browse or install toolchain components."
+      ;;
+    aliases)
+      echo "List, search, and explain configured aliases."
+      ;;
+    new)
+      echo "Create a new project from templates."
+      ;;
+    packages)
+      echo "List package managers and package stats."
+      ;;
+    log-rotate)
+      echo "Rotate dotfiles local log files."
+      ;;
+    setup)
+      echo "Interactive setup for profiles, features, and secrets."
+      ;;
+    theme)
+      echo "Switch terminal appearance theme."
+      ;;
+    wallpaper)
+      echo "Apply or sync wallpapers."
+      ;;
+    fonts)
+      echo "Install Nerd Fonts for terminal tooling."
+      ;;
+    tune)
+      echo "Apply OS-level tuning defaults."
+      ;;
+    secrets-init)
+      echo "Initialize age key for encrypted secrets."
+      ;;
+    secrets)
+      echo "Manage secrets (set/get/list/load/provider)."
+      ;;
+    env)
+      echo "Load secret buckets into shell exports."
+      ;;
+    secrets-create)
+      echo "Create a new encrypted secrets file."
+      ;;
+    ssh-key)
+      echo "Encrypt an SSH key using age."
+      ;;
+    backup)
+      echo "Create a compressed backup."
+      ;;
+    encrypt-check)
+      echo "Check disk encryption status."
+      ;;
+    firewall)
+      echo "Apply firewall hardening settings."
+      ;;
+    telemetry)
+      echo "Disable telemetry where supported."
+      ;;
+    dns-doh)
+      echo "Enable DNS-over-HTTPS."
+      ;;
+    lock-screen)
+      echo "Harden lock-screen idle policy."
+      ;;
+    usb-safety)
+      echo "Disable risky removable-media automount."
+      ;;
+    fleet)
+      echo "Show fleet node status, drift, and namespace."
+      ;;
+    upgrade)
+      echo "Update system toolchains, plugins, and dotfiles."
+      ;;
+    docs)
+      echo "Show dotfiles documentation."
+      ;;
+    learn)
+      echo "Start the interactive onboarding tour."
+      ;;
+    keys)
+      echo "Show keybindings catalog."
+      ;;
+    sandbox)
+      echo "Start isolated sandbox environment."
+      ;;
+    mcp)
+      echo "Run MCP configuration diagnostics."
+      ;;
+    metrics)
+      echo "Show recent observability metrics from JSONL."
+      ;;
+    cache-refresh | prewarm)
+      echo "Regenerate shell caches for ultra-fast startup."
+      ;;
+    search)
+      echo "Find commands by keyword."
+      ;;
+    help | --help | -h)
+      echo "Show command usage and reference."
+      ;;
+    --version | -v | version)
+      echo "Show dotfiles and environment versions."
+      ;;
+    *)
+      echo "Run a dotfiles command."
+      ;;
+  esac
+}
+
+dot_ui_command_banner() {
+  local section="${1:-Dot}"
+  local cmd="${2:-}"
+  shift 2 || true
+  local version summary
+
+  for arg in "$@"; do
+    case "$arg" in
+      --json | -j)
+        return
+        ;;
+    esac
+  done
+
+  ui_logo_once "Dot • $section"
+
+  if [[ "${DOTFILES_SHOW_LOGO:-1}" != "1" ]] || [[ ! -t 1 ]]; then
+    return
+  fi
+
+  version="$(dotfiles_version)"
+  summary="$(dot_command_summary "$cmd")"
+
+  ui_key_value "Version" "v${version}"
+  if [[ -n "$cmd" ]]; then
+    ui_key_value "Command" "dot ${cmd}"
+  fi
+  ui_key_value "Summary" "$summary"
+  printf "\n"
+}

package/scripts/fonts/install-nerd-fonts.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../dot/lib/ui.sh
+# shellcheck disable=SC1091
+source "$SCRIPT_DIR/../dot/lib/ui.sh"
+
+ui_init
+ui_header "Nerd Fonts"
+
+DEFAULT_FONTS="JetBrainsMono FiraCode Iosevka"
+FONT_LIST="${*:-$DEFAULT_FONTS}"
+
+install_linux() {
+  font_name="$1"
+  target_dir="$HOME/.local/share/fonts/${font_name}NerdFont"
+  mkdir -p "$target_dir"
+  tmp_dir="$(umask 077 && mktemp -d)"
+  # shellcheck disable=SC2064
+  trap "rm -rf '$tmp_dir'" RETURN
+  url="https://github.com/ryanoasis/nerd-fonts/releases/latest/download/${font_name}.zip"
+  ui_info "Downloading" "$font_name Nerd Font"
+  curl -fL --connect-timeout 10 --max-time 300 "$url" -o "$tmp_dir/${font_name}.zip"
+  if ! unzip -o "$tmp_dir/${font_name}.zip" -d "$target_dir" >/dev/null; then
+    ui_err "Unzip failed" "${font_name}.zip" >&2
+    return 1
+  fi
+  if command -v fc-cache >/dev/null; then
+    fc-cache -f "$target_dir"
+  fi
+  ui_ok "Installed" "$target_dir"
+}
+
+install_macos() {
+  font_name="$1"
+  if command -v brew >/dev/null; then
+    brew tap homebrew/cask-fonts >/dev/null 2>&1 || true
+    cask_name="$(printf "%s" "$font_name" | tr '[:upper:]' '[:lower:]')"
+    case "$cask_name" in
+      jetbrainsmono) cask_name="jetbrains-mono" ;;
+      firacode) cask_name="fira-code" ;;
+      iosevka) cask_name="iosevka" ;;
+    esac
+    brew install --cask "font-${cask_name}-nerd-font" || true
+  else
+    ui_err "Homebrew" "not found. Install font manually."
+    exit 1
+  fi
+}
+
+case "$(uname -s)" in
+  Linux)
+    for font in $FONT_LIST; do
+      install_linux "$font"
+    done
+    ;;
+  Darwin)
+    for font in $FONT_LIST; do
+      install_macos "$font"
+    done
+    ;;
+  *)
+    ui_err "Unsupported OS" "font install"
+    exit 1
+    ;;
+esac

package/scripts/fonts/patch-fonts.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+set -euo pipefail
+
+if [[ $# -lt 1 ]]; then
+  echo "Usage: patch-fonts.sh <font-file> [output-dir]" >&2
+  exit 1
+fi
+
+font_file="$1"
+out_dir="${2:-$PWD/patched-fonts}"
+
+if [[ ! -f "$font_file" ]]; then
+  echo "Font not found: $font_file" >&2
+  exit 1
+fi
+
+if ! command -v fontforge >/dev/null; then
+  echo "fontforge not found. Install it first (brew install fontforge / apt install fontforge)." >&2
+  exit 1
+fi
+
+patcher="${NERD_FONTS_PATCHER:-$HOME/.local/share/nerd-fonts/font-patcher}"
+
+if [[ ! -x "$patcher" ]]; then
+  echo "Nerd Fonts patcher not found: $patcher" >&2
+  echo "Set NERD_FONTS_PATCHER to the font-patcher path or clone nerd-fonts." >&2
+  exit 1
+fi
+
+mkdir -p "$out_dir"
+
+fontforge -script "$patcher" --complete --outputdir "$out_dir" "$font_file"
+
+echo "Patched font written to: $out_dir"

package/scripts/git-hooks/install.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+install -m 0755 "${repo_root}/scripts/git-hooks/pre-commit" "${repo_root}/.git/hooks/pre-commit"
+install -m 0755 "${repo_root}/scripts/git-hooks/pre-push" "${repo_root}/.git/hooks/pre-push"
+install -m 0755 "${repo_root}/scripts/git-hooks/prepare-commit-msg" "${repo_root}/.git/hooks/prepare-commit-msg"
+echo "Installed pre-commit hook at ${repo_root}/.git/hooks/pre-commit"
+echo "Installed pre-push hook at ${repo_root}/.git/hooks/pre-push"
+echo "Installed prepare-commit-msg hook at ${repo_root}/.git/hooks/prepare-commit-msg"

package/scripts/git-hooks/pre-commit

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+
+if [[ -x "${repo_root}/scripts/diagnostics/secret-governance.sh" ]]; then
+  "${repo_root}/scripts/diagnostics/secret-governance.sh"
+fi
+
+if [[ -x "${repo_root}/scripts/git-hooks/pre-commit-audit.sh" ]]; then
+  "${repo_root}/scripts/git-hooks/pre-commit-audit.sh"
+fi

package/scripts/git-hooks/pre-commit-audit.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# Dotfiles Pre-Commit Sentinel (Audit Hook)
+# Prevents secrets, hardcoded paths, and shell hygiene violations.
+
+set -euo pipefail
+
+_cleanup_files=()
+trap 'rm -f "${_cleanup_files[@]}"' EXIT
+
+# ANSI Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+BOLD='\033[1m'
+NC='\033[0m'
+
+printf '%b\\n' "${BOLD}🕵️  Running Pre-Commit Audit...${NC}"
+
+# Get list of staged files
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)
+
+if [[ -z "$STAGED_FILES" ]]; then
+  printf '%b\\n' "${GREEN}✓ No files staged. Skipping.${NC}"
+  exit 0
+fi
+
+FAILED=0
+
+# --- 🔐 1. Secret Scanning ---
+echo -n "   🔍 Scanning for secrets... "
+# Refined patterns: require assignment-like syntax to reduce false positives on documentation
+# Exclude assignments to values containing common placeholder strings or within template expressions
+SENSITIVE_PATTERNS="(GITHUB_TOKEN|API_KEY|SECRET|password|private_key|AKIA[0-9A-Z]{16})[[:space:]]*[:=]"
+# Exclusions list for legitimate variable checks or documentation
+SECRET_EXCLUDES="test_|assertions.sh|.pre-commit|README|CHANGELOG|FEATURES.md|CONFIG_STRATEGY.md|docs/|install/lib/|.chezmoitemplates/|mcp-doctor.sh|\.github/workflows/"
+# Also exclude .tmpl files from secret scanning as they contain many false positive markers
+if echo "$STAGED_FILES" | grep -v "\.tmpl" | xargs grep -EiE "$SENSITIVE_PATTERNS" /dev/null | grep -vE "$SECRET_EXCLUDES" | grep -viE "dummy|placeholder|example|test|sk-placeholder|\\{\\{" >/dev/null 2>&1; then
+  printf '%b\\n' "${RED}FAILED${NC}"
+  printf '%b\\n' "      ${YELLOW}⚠ Potential secret detected in staged files:${NC}"
+  echo "$STAGED_FILES" | grep -v "\.tmpl" | xargs grep -EiE "$SENSITIVE_PATTERNS" /dev/null | grep -vE "$SECRET_EXCLUDES" | grep -viE "dummy|placeholder|example|test|sk-placeholder|\\{\\{" | sed 's/^/      /'
+  FAILED=1
+else
+  printf '%b\\n' "${GREEN}PASSED${NC}"
+fi
+
+# --- 👻 2. Ghost Path Linter ---
+echo -n "   👻 Checking for hardcoded paths... "
+# Exclude test files, documentation, the hook itself, Nix files, and template backups
+GHOST_EXCLUDES="test_|assertions.sh|pre-commit|INTEROP.md|WSL2_NIX_TROUBLESHOOTING.md|\.nix|\.backup|\.github/workflows/"
+if echo "$STAGED_FILES" | xargs grep -rIE '"/home/(linuxbrew)?[^$]|/Users/[^$]' /dev/null | grep -v "linuxbrew" | grep -vE "$GHOST_EXCLUDES" >/dev/null 2>&1; then
+  printf '%b\\n' "${RED}FAILED${NC}"
+  printf '%b\\n' "      ${YELLOW}⚠ Literal home paths detected (use \$HOME or ~ instead):${NC}"
+  echo "$STAGED_FILES" | xargs grep -rIE '"/home/(linuxbrew)?[^$]|/Users/[^$]' /dev/null | grep -v "linuxbrew" | grep -vE "$GHOST_EXCLUDES" | sed 's/^/      /'
+  FAILED=1
+else
+  printf '%b\\n' "${GREEN}PASSED${NC}"
+fi
+
+# --- 🐚 3. ShellCheck Hygiene ---
+if command -v shellcheck >/dev/null 2>&1; then
+  echo -n "   🐚 Running ShellCheck... "
+  # ONLY run on actual .sh files, NOT .tmpl files (Go templates break shellcheck)
+  # Also exclude files that contain Zsh-specific syntax that might trigger false positives in sh mode
+  SHELL_FILES=$(echo "$STAGED_FILES" | grep -E '\.sh$' | grep -v "\.tmpl" || true)
+  if [[ -n "$SHELL_FILES" ]]; then
+    if ! echo "$SHELL_FILES" | xargs shellcheck -x --severity=error -e SC1091,SC2296,SC2142 >/dev/null 2>&1; then
+      printf '%b\\n' "${RED}FAILED${NC}"
+      printf '%b\\n' "      ${YELLOW}⚠ Shell syntax errors detected:${NC}"
+      echo "$SHELL_FILES" | xargs shellcheck -x --severity=error -e SC1091,SC2296,SC2142 | sed 's/^/      /'
+      FAILED=1
+    else
+      printf '%b\\n' "${GREEN}PASSED${NC}"
+    fi
+  else
+    printf '%b\\n' "${YELLOW}SKIPPED${NC} (no .sh files)"
+  fi
+fi
+# --- 🧹 4. Formatting Audit ---
+echo -n "   🧹 Checking formatting... "
+# Find files with trailing whitespace, excluding SVGs and other formats where it might be intentional or harmless
+OFFENDING_WHITESPACE=$(echo "$STAGED_FILES" | grep -vE '\.(svg|md)$' | xargs grep -l '[[:space:]]$' /dev/null || true)
+# Use defused patterns to avoid self-detection
+MERGE_START="^<<<<<<< "
+MERGE_END="^>>>>>>> "
+MERGE_DIV="^=======$"
+if [[ -n "$OFFENDING_WHITESPACE" ]]; then
+  printf '%b\\n' "${RED}FAILED${NC}"
+  printf '%b\\n' "      ${YELLOW}⚠ Trailing whitespace found in staged files:${NC}"
+  echo "      ${OFFENDING_WHITESPACE//$'\n'/$'\n'      }"
+  FAILED=1
+elif echo "$STAGED_FILES" | xargs grep -lE "$MERGE_START|$MERGE_END|$MERGE_DIV" /dev/null >/dev/null 2>&1; then
+  printf '%b\\n' "${RED}FAILED${NC}"
+  printf '%b\\n' "      ${YELLOW}⚠ Unresolved merge markers found in staged files:${NC}"
+  echo "$STAGED_FILES" | xargs grep -lE "$MERGE_START|$MERGE_END|$MERGE_DIV" /dev/null | sed 's/^/      /'
+  FAILED=1
+else
+  printf '%b\\n' "${GREEN}PASSED${NC}"
+fi
+
+# --- 🏛️ 5. Signature Guard ---
+if echo "$STAGED_FILES" | grep -q "^README.md$"; then
+  echo -n "   🏛️  Checking README signature... "
+  EXPECTED_ARCHITECT='**THE ARCHITECT** ᛫ [Sebastien Rousseau](https://sebastienrousseau.com)'
+  EXPECTED_ENGINE='**THE ENGINE** ᛞ [EUXIS](https://euxis.co) ᛫ Enterprise Unified Execution Intelligence System'
+  README_CONTENT=$(git show :README.md 2>/dev/null || cat README.md)
+  if echo "$README_CONTENT" | grep -qF "$EXPECTED_ARCHITECT" && echo "$README_CONTENT" | grep -qF "$EXPECTED_ENGINE"; then
+    printf '%b\\n' "${GREEN}PASSED${NC}"
+  else
+    # Auto-add the signature footer before ## License (or at EOF)
+    tmp_footer=$(mktemp)
+    _cleanup_files+=("$tmp_footer")
+    if grep -qF '## License' README.md; then
+      awk -v arch="$EXPECTED_ARCHITECT" -v eng="$EXPECTED_ENGINE" '
+        /^## License/ {
+          print "---"
+          print ""
+          print arch
+          print eng
+          print ""
+          print "---"
+          print ""
+        }
+        { print }
+      ' README.md >"$tmp_footer" && mv "$tmp_footer" README.md
+    else
+      {
+        printf '\n---\n\n%s\n%s\n\n---\n' "$EXPECTED_ARCHITECT" "$EXPECTED_ENGINE"
+      } >>README.md
+    fi
+    rm -f "$tmp_footer"
+    git add README.md
+    printf '%b\\n' "${GREEN}FIXED${NC} (auto-added)"
+  fi
+fi
+
+echo ""
+if [[ $FAILED -eq 1 ]]; then
+  printf '%b\\n' "${RED}${BOLD}❌ Audit failed.${NC} Please fix the issues above before committing."
+  printf '%b\\n' "   (Use --no-verify to bypass if absolutely necessary)"
+  exit 1
+else
+  printf '%b\n' "${GREEN}${BOLD}✅ Audit passed.${NC} v0.2.501 standards maintained."
+  exit 0
+fi