@sebastienrousseau/dotfiles 0.2.499 → 0.2.500

package/dot_local/bin/executable_dot

@@ -0,0 +1,589 @@
+#!/usr/bin/env bash
+# shellcheck disable=SC2034
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+set -euo pipefail
+
+# Dotfiles CLI Entry Point - v0.2.500
+
+# 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}"
+
+# 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 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 [ -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
+  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
+}
+
+_dot_help_overview_specs() {
+  cat <<'EOF'
+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
+}
+
+_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 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
+
+  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
+    ui_fail "Command module not found: $cmd_file"
+    exit 1
+  fi
+}
+
+if [[ -z "$COMMAND" ]]; then
+  show_help
+  exit 0
+fi
+
+route="$(_dot_command_route "$COMMAND" || true)"
+
+case "$route" in
+  core | diagnostics | ai | tools | appearance | secrets | security | meta | fleet)
+    _dispatch "$route" "$@"
+    ;;
+
+  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
+    ;;
+
+  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
+    ;;
+
+  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
+    ;;
+
+  help)
+    show_help "$@"
+    ;;
+
+  version)
+    show_version
+    ;;
+
+  # User-provided custom commands
+  *)
+    _user_cmd="${XDG_CONFIG_HOME:-$HOME/.config}/dotfiles/commands/${COMMAND}.sh"
+    if [[ -f "$_user_cmd" ]]; then
+      source "$_user_cmd" "$@"
+    else
+      echo "Unknown command: ${COMMAND:-}" >&2
+      echo "Run 'dot help' for available commands." >&2
+      exit 1
+    fi
+    ;;
+esac

package/dot_local/bin/executable_dot-ai

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# shellcheck disable=SC2034,SC1091
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# Dotfiles AI RAG (Retrieval-Augmented Generation)
+# Usage: dot ai-query "how do I list files?"
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+# shellcheck source=../scripts/dot/lib/ui.sh
+source "$HOME/.dotfiles/scripts/dot/lib/ui.sh"
+
+QUERY="${1:-}"
+if [[ -z "$QUERY" ]]; then
+  echo "Usage: dot ai-query 'your question'"
+  exit 1
+fi
+
+DOTFILES_DIR="${HOME}/.dotfiles"
+
+ui_info "Searching dotfiles context for: $QUERY..."
+# 1. Retrieval: Use ripgrep to find relevant snippets from docs and configs
+CONTEXT=$(rg -i --no-filename --no-line-number -C 2 -m 10 "$(echo "$QUERY" | tr ' ' '|')" "$DOTFILES_DIR/docs" "$DOTFILES_DIR/dot_config/shell" "$DOTFILES_DIR/.chezmoitemplates" 2>/dev/null || true)
+
+if [[ -z "$CONTEXT" ]]; then
+  CONTEXT="No specific context found in the local repository."
+fi
+
+# 2. Augmented Generation: Pipe to the Dotfiles AI Bridge
+# We use the 'architect' pattern to ensure the AI knows how to interpret dotfiles
+ui_info "Generating context-aware answer..."
+dot cl --pattern architect "Answer the following question based on this local dotfiles context:
+---
+$CONTEXT
+---
+User Question: $QUERY"