@sebastienrousseau/dotfiles 0.2.481 → 0.2.500

package/dot_local/bin/executable_dot

@@ -1,177 +1,588 @@
 #!/usr/bin/env bash
-# Dotfiles CLI Entry Point - v0.2.481
-# Modular architecture with command handlers in scripts/dot/commands/
+# shellcheck disable=SC2034
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+set -euo pipefail
 
-set -e
+# Dotfiles CLI Entry Point - v0.2.500
 
-VERSION="0.2.481"
+# Ensure XDG Base Directory variables are set
+export XDG_CONFIG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}"
+export XDG_CACHE_HOME="${XDG_CACHE_HOME:-$HOME/.cache}"
+export XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
+export XDG_STATE_HOME="${XDG_STATE_HOME:-$HOME/.local/state}"
 
-COMMAND="$1"
-if [ -n "$1" ]; then
+# Ensure PIPX paths are set
+export PIPX_HOME="${XDG_DATA_HOME}/pipx"
+export PIPX_BIN_DIR="${HOME}/.local/bin"
+
+# Ensure Nix is in PATH if installed
+if [ -e "${HOME}/.nix-profile/etc/profile.d/nix.sh" ]; then
+  # shellcheck disable=SC1091
+  . "${HOME}/.nix-profile/etc/profile.d/nix.sh"
+fi
+
+VERSION="0.2.500"
+
+COMMAND="${1:-}"
+if [ -n "${1:-}" ]; then
   shift
 fi
 
-# Resolve the dotfiles source directory
-resolve_source_dir() {
-  if [ -n "${CHEZMOI_SOURCE_DIR:-}" ] && [ -d "$CHEZMOI_SOURCE_DIR" ]; then
-    echo "$CHEZMOI_SOURCE_DIR"
-    return
+# Resolve source directory (needed early for ui.sh sourcing)
+_resolve_source_dir() {
+  local dir=""
+  local script_path=""
+  local script_dir=""
+  local repo_candidate=""
+
+  if script_path="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd 2>/dev/null)"; then
+    script_dir="$script_path"
+    repo_candidate="$(cd "$script_dir/../.." && pwd 2>/dev/null || true)"
+    if [ -n "$repo_candidate" ] && [ -f "$repo_candidate/scripts/dot/lib/ui.sh" ]; then
+      dir="$repo_candidate"
+    fi
   fi
-  if [ -d "$HOME/.dotfiles" ]; then
-    echo "$HOME/.dotfiles"
-    return
+
+  if [ -z "$dir" ] && [ -n "${CHEZMOI_SOURCE_DIR:-}" ] && [ -d "$CHEZMOI_SOURCE_DIR" ]; then
+    dir="$CHEZMOI_SOURCE_DIR"
+  elif [ -z "$dir" ] && [ -d "$HOME/.dotfiles" ]; then
+    dir="$HOME/.dotfiles"
+  elif [ -z "$dir" ] && [ -d "$HOME/.local/share/chezmoi" ]; then
+    dir="$HOME/.local/share/chezmoi"
+  elif [ -z "$dir" ] && [ -f "package.json" ] && grep -q '"name": "dotfiles"' package.json 2>/dev/null; then
+    dir="$(pwd)"
   fi
-  if [ -d "$HOME/.local/share/chezmoi" ]; then
-    echo "$HOME/.local/share/chezmoi"
-    return
+  echo "$dir"
+}
+
+# Source shared UI library for consistent colors, checkmarks, and formatting.
+# Falls back to minimal inline definitions if the source directory is unavailable.
+_DOT_SRC="$(_resolve_source_dir)"
+if [ -n "$_DOT_SRC" ] && [ -f "$_DOT_SRC/scripts/dot/lib/ui.sh" ]; then
+  # shellcheck source=../../scripts/dot/lib/ui.sh
+  # shellcheck disable=SC1091
+  source "$_DOT_SRC/scripts/dot/lib/ui.sh"
+  ui_init
+else
+  # Minimal fallback when source dir is not available (e.g. first install)
+  # shellcheck disable=SC2034
+  UI_COLOR=0
+  BOLD=""
+  NORMAL=""
+  RED=""
+  GREEN=""
+  YELLOW=""
+  BLUE=""
+  CYAN=""
+  GRAY=""
+  MAGENTA=""
+  ui_init() {
+    if [[ -t 1 ]] && [[ -z "${NO_COLOR:-}" ]]; then
+      UI_COLOR=1
+      BASH_BOLD=$'\033[1m'
+      NORMAL=$'\033[0m'
+      RED=$'\033[38;5;196m'
+      GREEN=$'\033[38;5;42m'
+      YELLOW=$'\033[38;5;214m'
+      BLUE=$'\033[38;5;63m'
+      CYAN=$'\033[38;5;81m'
+      GRAY=$'\033[38;5;244m'
+      MAGENTA=$'\033[38;5;211m'
+    fi
+  }
+  ui_header() {
+    ui_init
+    printf "\n  %s%s%s\n\n" "${BOLD}${BLUE}" "$1" "$NORMAL"
+  }
+  ui_section() {
+    ui_init
+    printf "  %s%s%s\n" "${BOLD}${CYAN}" "$1" "$NORMAL"
+  }
+  ui_cmd() {
+    ui_init
+    printf "  %s•%s %s%-16s%s %s\n" "$GREEN" "$NORMAL" "$GREEN" "$1" "$NORMAL" "$2"
+  }
+  ui_ok() {
+    ui_init
+    printf "  %s✓%s %-35s %s\n" "$GREEN" "$NORMAL" "$1" "${2:-}"
+  }
+  ui_info() {
+    ui_init
+    printf "  %s•%s %-35s %s\n" "$GRAY" "$NORMAL" "$1" "${2:-}"
+  }
+  ui_meta() {
+    ui_init
+    printf "  %s•%s %-14s %s\n" "$GRAY" "$NORMAL" "$1" "${2:-}"
+  }
+  ui_kv() {
+    ui_init
+    printf "  %s%-14s%s %s\n" "$BOLD" "$1" "$NORMAL" "$2"
+  }
+  ui_warn() {
+    ui_init
+    printf "  %s⚠%s %-35s %s\n" "$YELLOW" "$NORMAL" "$1" "${2:-}"
+  }
+  ui_err() {
+    ui_init
+    printf "  %s✗%s %-35s %s\n" "$RED" "$NORMAL" "$1" "${2:-}" >&2
+  }
+  ui_clear_line() { printf '\r\033[K'; }
+  ui_toast() { case "$1" in success | ok) ui_ok "$2" ;; error | err) ui_err "$2" ;; warn) ui_warn "$2" ;; *) ui_info "$2" ;; esac }
+fi
+
+# Alias ui_fail → ui_err for backward compatibility in this script
+ui_fail() { ui_err "$@"; }
+
+ui_dot_banner() {
+  local section="${1:-Dot}"
+  if declare -F ui_product_banner >/dev/null 2>&1; then
+    ui_product_banner "Dot • $section"
+    return 0
+  fi
+  if declare -F ui_logo_dot >/dev/null 2>&1; then
+    ui_logo_dot "Dot • $section"
   fi
+}
+
+show_version() {
+  ui_dot_banner "Reference"
+  ui_header "Dotfiles Version"
   echo ""
+  ui_ok "Version" ".dotfiles $VERSION"
+  if [[ -n "$_DOT_SRC" ]]; then
+    ui_ok "Source" "$_DOT_SRC"
+  fi
 }
 
-show_help() {
+_dot_help_overview_specs() {
   cat <<'EOF'
-Usage: dot [command]
-
-Core Commands:
-  apply       Apply dotfiles (chezmoi apply)
-  sync        Apply dotfiles (alias of apply)
-  update      Pull latest changes and apply them (chezmoi update)
-  add         Add a file to chezmoi source
-  diff        Show chezmoi diff with exclusions
-  status      Show configuration drift (chezmoi status)
-  remove      Safely remove a managed file
-  cd          Print source directory path (use: cd $(dot cd))
-  edit        Open chezmoi source in $EDITOR
-
-Diagnostics:
-  doctor         Check system health and configuration
-  heal           Auto-repair common dotfiles issues
-  health         Run comprehensive health dashboard
-  security-score Security assessment with grading
-  rollback       Rollback dotfiles to a previous state
-  restore        Restore from backup or git ref
-  drift          Drift dashboard (detailed chezmoi status)
-  history        Shell history analysis
-  benchmark      Run shell startup benchmark (--detailed, --profile)
-
-Tools:
-  tools       Show or install nix packages (dot tools [install])
-  new         Create a new project from a template
-  sandbox     Launch a safe sandbox preview (Docker/Podman)
-  keys        Show keybindings catalog
-  learn       Start the interactive tour of your new tools
-  docs        Show repo README
-  log-rotate  Rotate ~/.local/share/dotfiles.log
-
-Appearance:
-  theme       Switch terminal theme (dark/light)
-  wallpaper   Apply a wallpaper from your library
-  fonts       Install Nerd Fonts (JetBrainsMono by default)
-  tune        Apply OS tuning (opt-in)
-
-Secrets:
-  secrets-init    Initialize age key for secrets
-  secrets         Edit encrypted secrets (age)
-  secrets-create  Create an encrypted secrets file
-  ssh-key         Encrypt an SSH key locally with age
-
-Security (opt-in):
-  backup        Create a compressed backup of your home
-  encrypt-check Check disk encryption status
-  firewall      Apply firewall hardening
-  telemetry     Disable OS telemetry
-  dns-doh       Enable DNS-over-HTTPS
-  lock-screen   Enforce lock screen idle settings
-  usb-safety    Disable automount for removable media
-
-Meta:
-  upgrade     Update flake, plugins, and dotfiles
-  packages    List installed packages and package managers
-  --version   Show version information
-  help        Show this help message
+Start Here|sync|Apply dotfiles to this machine.|Use after clone or after changes.
+Start Here|doctor|Check the environment and surface issues.|Use when something feels off.
+Start Here|learn|Open the guided tour.|Best first stop for new users.
+Start Here|help|Show the overview or help for one command.|Use `dot help <command>` for detail.
+Daily Use|status|Show local drift.|See what changed since the last apply.
+Daily Use|diff|Preview pending changes.|Safe way to inspect before applying.
+Daily Use|edit|Open the source directory.|Use the configured editor.
+Daily Use|upgrade|Update tools and dotfiles.|Runs the managed upgrade path.
+Inspect and Repair|doctor|Run the main health check.|Supports deeper audit flags.
+Inspect and Repair|attest|Export workstation evidence.|Use `--json|-j`, `--write|-w`, or `--fleet-store|-F`.
+Inspect and Repair|rollback|Return to a previous state.|Use after a broken change.
+Inspect and Repair|lint|Check shell script quality.|Supports `--check|-c` and `--fix|-f`.
+AI and Agents|ai|Show installed AI tools.|Launches the AI status view.
+AI and Agents|mcp|Inspect MCP policy and registry.|Supports `--strict|-s` and `--json|-j`.
+AI and Agents|mode|Show or set the agent profile.|Profiles: ask, plan, apply, audit.
+AI and Agents|agent|Show agent metadata, logs, checkpoints, and conformance.|Use for card, log, checkpoint, and conformance.
+Fleet|fleet|Show fleet node status, drift, and namespace.|Enterprise fleet management.
+Configuration|env|Show managed tool versions.|Backed by mise.
+Configuration|profile|Show or switch the active profile.|Use for machine-specific behavior.
+Configuration|secrets|Edit or manage encrypted secrets.|Subcommands cover set, get, list, load.
+Configuration|theme|Switch the terminal theme.|Light or dark.
+Reference|search|Find commands by keyword.|Example: `dot search security`.
+Reference|help all|Show the full command reference.|Lists every public command.
+Reference|version|Show version information.|Matches `dot --version`.
 EOF
 }
 
-# Dispatch to command module
-dispatch() {
-  local module="$1"
-  local cmd="$2"
-  shift 2
+_dot_help_specs() {
+  cat <<'EOF'
+Core|sync|Apply dotfiles (alias for apply; --pull to fetch, --check to preview)|Use after clone or after changes.
+Core|add|Add a file to chezmoi source|Start managing a file in the source tree.
+Core|diff|Show chezmoi diff with exclusions|Preview pending changes before apply.
+Core|status|Show configuration drift (chezmoi status)|Inspect the current managed state.
+Core|edit|Open chezmoi source in $EDITOR|Jump into the source tree quickly.
+Core|cd|Print source directory path (use: cd $(dot cd))|Useful in shell scripts and jump helpers.
+Core|commit|AI-powered conventional commit|Wraps the commit helper flow.
+Diagnostics|doctor|Deep audit: tools, paths, portability, AI analysis (--ai|-A)|Main health and repair entrypoint.
+Diagnostics|attest|Export workstation attestation evidence (--json|-j, --write|-w, --fleet-store|-F)|Produce machine-readable evidence.
+Diagnostics|score|System health and security scorecard|Quick high-level readout.
+Diagnostics|snapshot|Capture baseline system snapshot|Use before larger changes.
+Diagnostics|chaos|Simulate config corruption to test self-healing|Advanced validation path.
+Diagnostics|bundle|Create offline archive of dotfiles environment|Portable support artifact.
+Diagnostics|rollback|Rollback dotfiles to a previous state|Use after a bad apply.
+Diagnostics|history|Shell history analysis|Inspect command usage patterns.
+Diagnostics|perf|Show performance mode and quick timing|Startup and shell timing surface.
+Diagnostics|metrics|Show recent observability metrics (JSONL)|Recent runtime events and counters.
+Diagnostics|load-bench|Measure time to heavy-layer readiness|Performance benchmarking helper.
+AI|ai|AI CLI status & launcher|Overview of installed AI tools.
+AI|ai-setup|Interactive setup for all AI CLI tools|Initial AI tool bootstrap.
+AI|ai-query|Context-aware RAG query over your dotfiles|Ask questions over the repo state.
+AI|mcp|Inspect MCP policy, supply chain, and registry|Governance and validation surface.
+AI|mode|Set or inspect agent operating profiles (ask/plan/apply/audit)|Bounded-autonomy controls.
+AI|agent|Profile-aware execution, agent card, a2a-card, session log, checkpoints, and conformance|Agent metadata and local audit trail.
+AI|cl|Claude CLI with context patterns|Context-aware Anthropic bridge.
+AI|copilot|GitHub Copilot CLI with context patterns|Context-aware Copilot bridge.
+AI|gemini|Gemini CLI with context patterns|Context-aware Gemini bridge.
+AI|kiro|Kiro CLI with context patterns|Context-aware Kiro bridge.
+AI|sgpt|Shell-GPT with context patterns|Context-aware Shell-GPT bridge.
+AI|ollama|Ollama with context patterns|Context-aware local-model bridge.
+AI|opencode|OpenCode with context patterns|Context-aware OpenCode bridge.
+AI|aider|Aider with context patterns|Context-aware Aider bridge.
+Tools|env|Tool versions (mise)|Managed runtime versions.
+Tools|profile|Show/switch configuration profile|Profile-specific behavior.
+Tools|keys|Keybindings (sign-check: verify git signing)|Keyboard and signing references.
+Tools|tools|Show or install nix packages|Package helper entrypoint.
+Tools|new|Create a new project from a template|Project scaffold helper.
+Tools|sandbox|Launch a safe sandbox preview (Docker/Podman)|Disposable environment for testing.
+Tools|lint|Lint shell scripts (--fix|-f to auto-format, --check|-c for CI)|Shell quality gate.
+Tools|learn|Start the interactive tour of your new tools|Guided onboarding.
+Tools|docs|Show repo README|Open the main documentation.
+Appearance|theme|Switch terminal theme (dark/light)|Terminal appearance control.
+Appearance|wallpaper|Apply a wallpaper from your library [macOS,Linux]|Desktop customization helper.
+Appearance|fonts|Install Nerd Fonts (JetBrainsMono by default)|Font bootstrap helper.
+Appearance|tune|Apply OS tuning (opt-in) [macOS,Linux]|Host tuning entrypoint.
+Secrets|secrets-init|Initialize age key for secrets|First-time secrets setup.
+Secrets|secrets|Edit encrypted secrets (age)|Primary secrets entrypoint.
+Secrets|secrets-create|Create an encrypted secrets file|Create a new secret payload.
+Secrets|ssh-key|Encrypt an SSH key locally with age|Protect local SSH keys.
+Secrets|ssh-cert|Manage short-lived SSH certificates|SSH certificate workflow.
+Security (opt-in)|backup|Create a compressed backup of your home|Safety copy before risky changes.
+Security (opt-in)|encrypt-check|Check disk encryption status|Host security inspection.
+Security (opt-in)|firewall|Apply firewall hardening [macOS,Linux]|Opt-in host hardening.
+Security (opt-in)|telemetry|Disable OS telemetry [macOS,Linux]|Privacy-focused host control.
+Security (opt-in)|dns-doh|Enable DNS-over-HTTPS [macOS,Linux]|Secure DNS helper.
+Security (opt-in)|lock-screen|Enforce lock screen idle settings [Linux]|Linux workstation hardening.
+Security (opt-in)|usb-safety|Disable automount for removable media [Linux]|Linux removable-media hardening.
+Fleet|fleet|Show fleet node status, drift, and namespace (--json for machine output)|Fleet management surface.
+Fleet|fleet drift|Check for configuration drift across managed files|Drift detection and reporting.
+Fleet|fleet namespace|Show or set the active namespace for multi-tenant isolation|Namespace management.
+Fleet|fleet events|Show recent fleet events from local event log|Fleet observability.
+Meta|upgrade|Update system toolchains, plugins, and dotfiles|Managed upgrade flow.
+Meta|packages|List installed packages and package managers|Inventory and package surfaces.
+Meta|cache-refresh|Regenerate shell caches for ultra-fast startup|Refresh generated shell state.
+Meta|search|Find commands by keyword|Find the right command quickly.
+Meta|version|Show version information.|Matches `dot --version`.
+Meta|help|Show this help message|Overview or focused command help.
+EOF
+}
+
+_dot_help_details() {
+  cat <<'EOF'
+sync|Apply the current dotfiles to this machine.|dot sync\ndot sync --check
+add|Start managing a file with chezmoi.|dot add ~/.gitconfig
+diff|Show pending dotfile changes before applying.|dot diff
+status|Show local drift in the managed home state.|dot status
+edit|Open the dotfiles source tree in the configured editor.|dot edit
+upgrade|Run the managed update path for tools and dotfiles.|dot upgrade
+doctor|Inspect shell tools, paths, portability, and health.|dot doctor\ndot doctor --score\ndot doctor -H
+attest|Export workstation attestation evidence.|dot attest\ndot attest --json\ndot attest -F /srv/dotfiles-fleet
+health|Run the health dashboard with optional fixes.|dot health -v\ndot health -j\ndot health -f
+perf|Measure shell performance and emit structured timing.|dot perf -j -r 1\ndot perf -p\ndot perf -t 200
+security-score|Assess workstation security posture.|dot security-score -j\ndot security-score -q
+snapshot|Capture the current workstation snapshot.|dot snapshot -b\ndot snapshot -b -f
+verify|Run post-change verification checks.|dot verify\ndot verify -s
+restore|Restore from a backup or git ref.|dot restore -l\ndot restore -L\ndot restore -g HEAD~1
+rollback|Restore a previous configuration snapshot.|dot rollback
+lint|Run shell quality checks for the repo.|dot lint\ndot lint -c\ndot lint -f
+ai|Show installed AI tools and entrypoints.|dot ai
+mcp|Inspect MCP configuration, policy, and registry.|dot mcp\ndot mcp -s -j\ndot mcp registry
+mode|Inspect or switch the active agent mode.|dot mode list\ndot mode show ask\ndot mode set audit
+agent|Inspect agent metadata or run profile-aware actions.|dot agent card\ndot agent a2a-card --validate\ndot agent checkpoint list\ndot agent conformance --strict --json
+fleet|Show fleet node status, drift, and namespace.|dot fleet\ndot fleet status --json\ndot fleet drift\ndot fleet namespace set engineering
+env|Show managed tool versions and runtime state.|dot env
+profile|Show or switch the active configuration profile.|dot profile
+secrets|Manage encrypted secrets and environment loading.|dot secrets edit\ndot secrets list\ndot secrets load ai
+theme|Switch the terminal theme.|dot theme light\ndot theme dark
+learn|Open the guided tour of the toolchain.|dot learn
+search|Find commands by keyword across the public surface.|dot search ai
+help|Show the overview or a focused command reference.|dot help\ndot help doctor\ndot help all
+--version|Show the installed dotfiles version.|dot --version\ndot version
+version|Show the installed dotfiles version.|dot --version\ndot version
+EOF
+}
+
+_dot_help_summary() {
+  local command_name="${1:-}"
+  awk -F'|' -v command_name="$command_name" '$1 == command_name { print $2; exit }' < <(_dot_help_details)
+}
+
+_dot_help_examples() {
+  local command_name="${1:-}"
+  awk -F'|' -v command_name="$command_name" '$1 == command_name { print $3; exit }' < <(_dot_help_details)
+}
+
+_dot_command_routes() {
+  cat <<'EOF'
+sync|core
+apply|core
+update|core
+add|core
+diff|core
+status|core
+remove|core
+cd|core
+edit|core
+commit|core
+clean-cache|core
+doctor|diagnostics
+scorecard|diagnostics
+score|diagnostics
+snapshot|diagnostics
+history|diagnostics
+perf|diagnostics
+load-bench|diagnostics
+load-bench-pty|diagnostics
+chaos|diagnostics
+bundle|diagnostics
+rollback|diagnostics
+heal|diagnostics
+health|diagnostics
+health-check|diagnostics
+smoke-test|diagnostics
+verify|diagnostics
+attest|diagnostics
+attestation|diagnostics
+security-score|diagnostics
+drift|diagnostics
+benchmark|diagnostics
+intelligence|diagnostics
+conflicts|diagnostics
+locks|diagnostics
+restore|diagnostics
+metrics|diagnostics
+ai|ai
+ai-setup|ai
+ai-query|ai
+cl|ai
+claude|ai
+gemini|ai
+kiro|ai
+sgpt|ai
+ollama|ai
+opencode|ai
+aider|ai
+env|tools
+profile|tools
+tools|tools
+new|tools
+packages|tools
+aliases|tools
+alias-check|tools
+setup|tools
+log-rotate|tools
+lint|tools
+theme|appearance
+wallpaper|appearance
+fonts|appearance
+tune|appearance
+secrets-init|secrets
+secrets|secrets
+secrets-create|secrets
+ssh-key|secrets
+ssh-cert|secrets
+backup|security
+encrypt-check|security
+firewall|security
+telemetry|security
+dns-doh|security
+lock-screen|security
+usb-safety|security
+upgrade|meta
+cache-refresh|meta
+prewarm|meta
+docs|meta
+learn|meta
+keys|meta
+sandbox|meta
+mcp|meta
+mode|meta
+agent|meta
+fleet|fleet
+patterns|patterns
+manual|manual
+search|search
+help|help
+--help|help
+-h|help
+--version|version
+-v|version
+version|version
+EOF
+}
+
+_dot_command_route() {
+  local command_name="${1:-}"
+  if [[ -z "$command_name" ]]; then
+    return 1
+  fi
+  awk -F'|' -v command_name="$command_name" '$1 == command_name { print $2; exit }' < <(_dot_command_routes)
+}
+
+show_help_overview() {
+  ui_dot_banner "Reference"
+  ui_header "Dotfiles"
+  ui_meta "Usage" "dot [command]"
+  ui_meta "Version" "v$VERSION"
+  echo ""
+
+  ui_info "What it is" "A single command for setting up, checking, and maintaining this shell environment."
+  ui_info "Platforms" "macOS, Linux, and WSL"
+  ui_info "Start" "Run 'dot sync', then 'dot doctor', then 'dot learn'"
+  echo ""
 
-  local src_dir
-  src_dir="$(resolve_source_dir)"
-  if [ -z "$src_dir" ]; then
-    echo "Dotfiles source not found." >&2
+  local current_section="" section="" command_name="" description="" detail=""
+  while IFS='|' read -r section command_name description detail; do
+    if [[ "$section" != "$current_section" ]]; then
+      if [[ -n "$current_section" ]]; then
+        echo ""
+      fi
+      ui_section "$section"
+      current_section="$section"
+    fi
+    ui_cmd "$command_name" "$description"
+  done < <(_dot_help_overview_specs)
+  echo ""
+  ui_info "Next" "Run 'dot help all' for the full command list"
+  ui_info "Detail" "Run 'dot help <command>' for one command"
+}
+
+show_help_all() {
+  ui_dot_banner "Reference"
+  ui_header "Dotfiles Command Reference"
+  ui_meta "Usage" "dot [command]"
+  ui_meta "Version" "v$VERSION"
+  echo ""
+
+  local current_section="" section="" command_name="" description="" detail=""
+  while IFS='|' read -r section command_name description detail; do
+    if [[ "$command_name" == "help all" ]]; then
+      continue
+    fi
+    if [[ "$section" != "$current_section" ]]; then
+      if [[ -n "$current_section" ]]; then
+        echo ""
+      fi
+      ui_section "$section"
+      current_section="$section"
+    fi
+    ui_cmd "$command_name" "$description"
+  done < <(_dot_help_specs)
+}
+
+show_help_command() {
+  local command_name="${1:-}"
+  local normalized summary examples
+
+  normalized="$command_name"
+  if [[ "$command_name" == "version" || "$command_name" == "-v" ]]; then
+    normalized="--version"
+  fi
+
+  summary="$(_dot_help_summary "$normalized")"
+  examples="$(_dot_help_examples "$normalized")"
+
+  if [[ -z "$summary" ]]; then
+    ui_fail "Unknown help topic: $command_name"
+    ui_info "Hint" "Try 'dot help all' or 'dot search <keyword>'"
     exit 1
   fi
 
-  local module_path="$src_dir/scripts/dot/commands/$module.sh"
-  if [ -f "$module_path" ]; then
-    exec bash "$module_path" "$cmd" "$@"
+  ui_dot_banner "Reference"
+  ui_header "dot $command_name"
+  echo ""
+  ui_info "Summary" "$summary"
+  if [[ -n "$examples" ]]; then
+    echo ""
+    ui_section "Examples"
+    while IFS= read -r example; do
+      [[ -n "$example" ]] || continue
+      ui_cmd "$example" ""
+    done < <(printf '%b\n' "$examples")
+  fi
+}
+
+show_help() {
+  local topic="${1:-}"
+  case "$topic" in
+    "")
+      show_help_overview
+      ;;
+    all)
+      show_help_all
+      ;;
+    *)
+      show_help_command "$topic"
+      ;;
+  esac
+}
+
+resolve_source_dir() { _resolve_source_dir; }
+
+# ─── Dispatcher ───────────────────────────────────────────────────────────────
+# Routes COMMAND to the appropriate command module in scripts/dot/commands/.
+# Each module receives the original COMMAND as its first argument so that its
+# internal case statement can dispatch to the right sub-function.
+_SOURCE_DIR="$(_resolve_source_dir)"
+_CMD_DIR="${_SOURCE_DIR}/scripts/dot/commands"
+
+_dispatch() {
+  local module="$1"
+  shift # remove module name; remaining $@ are the user's extra args
+  local cmd_file="${_CMD_DIR}/${module}.sh"
+  if [[ -f "$cmd_file" ]]; then
+    # shellcheck disable=SC1090
+    exec bash "$cmd_file" "$COMMAND" "$@"
   else
-    echo "Command module not found: $module" >&2
+    ui_fail "Command module not found: $cmd_file"
     exit 1
   fi
 }
 
-case "$COMMAND" in
-  # Version
-  --version|-v|version)
-    echo "dot v${VERSION}"
-    echo "Dotfiles CLI - Cross-platform shell environment distribution"
-    echo ""
-    echo "Repository: https://github.com/sebastienrousseau/dotfiles"
-    echo "Managed by: chezmoi $(chezmoi --version 2>/dev/null | head -1 || echo 'not installed')"
-    exit 0
-    ;;
-
-  # Core commands
-  apply|sync|update|add|diff|status|remove|cd|edit)
-    dispatch "core" "$COMMAND" "$@"
-    ;;
+if [[ -z "$COMMAND" ]]; then
+  show_help
+  exit 0
+fi
 
-  # Diagnostics
-  doctor|heal|health|health-check|security-score|rollback|restore|drift|history|benchmark)
-    dispatch "diagnostics" "$COMMAND" "$@"
-    ;;
+route="$(_dot_command_route "$COMMAND" || true)"
 
-  # Tools
-  tools|new|packages|log-rotate)
-    dispatch "tools" "$COMMAND" "$@"
+case "$route" in
+  core | diagnostics | ai | tools | appearance | secrets | security | meta | fleet)
+    _dispatch "$route" "$@"
     ;;
 
-  # Appearance
-  theme|wallpaper|fonts|tune)
-    dispatch "appearance" "$COMMAND" "$@"
+  manual)
+    if [[ -n "$_SOURCE_DIR" ]] && [[ -f "$_SOURCE_DIR/scripts/dot/commands/manual.sh" ]]; then
+      exec bash "$_SOURCE_DIR/scripts/dot/commands/manual.sh" "$@"
+    else
+      ui_fail "manual.sh not found"
+      exit 1
+    fi
     ;;
 
-  # Secrets
-  secrets-init|secrets|secrets-create|ssh-key)
-    dispatch "secrets" "$COMMAND" "$@"
+  patterns)
+    if [[ -n "$_SOURCE_DIR" ]] && [[ -f "$_SOURCE_DIR/scripts/dot/commands/patterns.sh" ]]; then
+      exec bash "$_SOURCE_DIR/scripts/dot/commands/patterns.sh" "$@"
+    else
+      ui_fail "patterns.sh not found"
+      exit 1
+    fi
     ;;
 
-  # Security
-  backup|encrypt-check|firewall|telemetry|dns-doh|lock-screen|usb-safety)
-    dispatch "security" "$COMMAND" "$@"
+  search)
+    keyword="${1:-}"
+    if [[ -z "$keyword" ]]; then
+      echo "Usage: dot search <keyword>"
+      exit 1
+    fi
+    show_help_all | grep -i --color=auto "$keyword" || echo "No commands matching '$keyword'"
+    exit 0
     ;;
 
-  # Meta
-  upgrade|docs|learn|keys|sandbox)
-    dispatch "meta" "$COMMAND" "$@"
+  help)
+    show_help "$@"
     ;;
 
-  # Help
-  help|--help|-h)
-    show_help
+  version)
+    show_version
     ;;
 
-  # Unknown or empty
+  # User-provided custom commands
   *)
-    if [ -z "$COMMAND" ]; then
-      show_help
+    _user_cmd="${XDG_CONFIG_HOME:-$HOME/.config}/dotfiles/commands/${COMMAND}.sh"
+    if [[ -f "$_user_cmd" ]]; then
+      source "$_user_cmd" "$@"
     else
-      echo "Unknown command: $COMMAND"
-      echo "Try 'dot help' for usage."
+      echo "Unknown command: ${COMMAND:-}" >&2
+      echo "Run 'dot help' for available commands." >&2
       exit 1
     fi
     ;;