@sebastienrousseau/dotfiles 0.2.511 → 0.2.513

package/scripts/diagnostics/health.sh

@@ -198,6 +198,11 @@ check_dotfiles_core() {
 check_shell_env() {
   check_section "Shell Environment"
   local current_shell="${SHELL##*/}"
+  local default_shell="fish"
+  if [[ -f "$SCRIPT_DIR/../../defaults/.chezmoidata.toml" ]]; then
+    default_shell="$(awk -F= '/^[[:space:]]*default_shell[[:space:]]*=/{split($2, value, "#"); gsub(/[ "]/, "", value[1]); print value[1]; exit}' "$SCRIPT_DIR/../../defaults/.chezmoidata.toml")"
+    default_shell="${default_shell:-fish}"
+  fi
 
   if has_command zsh; then
     check "Zsh installed" "pass"
@@ -210,12 +215,12 @@ check_shell_env() {
     check "Zsh installed" "fail"
   fi
 
-  if [[ -d "${ZINIT_HOME:-$HOME/.local/share/zinit}" ]]; then
+  if [[ -f "${ZINIT_HOME:-$HOME/.local/share/zinit/zinit.git}/zinit.zsh" ]] || [[ -d "${ZINIT_HOME:-$HOME/.local/share/zinit}" ]]; then
     check "Zinit plugin manager" "pass"
-  elif [[ "$current_shell" == "zsh" ]]; then
+  elif [[ "$current_shell" == "zsh" && "$default_shell" == "zsh" ]]; then
     check "Zinit plugin manager" "warn" "Not found"
   else
-    check "Zinit plugin manager" "pass" "Not required for $current_shell"
+    check "Zinit plugin manager" "pass" "Not required for $default_shell"
   fi
 
   if has_command starship; then
@@ -381,7 +386,10 @@ check_performance() {
 
   if has_command zsh; then
     local startup_time
-    startup_time=$({ time zsh -i -c exit; } 2>&1 | grep real | awk '{print $2}' | sed 's/[ms]//g')
+    # Startup timing is diagnostic only. A user's interactive configuration
+    # may exit non-zero or omit a `real` row, which must not abort health under
+    # `set -euo pipefail` before the summary is printed.
+    startup_time=$({ time zsh -i -c exit; } 2>&1 | awk '/real/ { print $2; exit }' | sed 's/[ms]//g' || true)
     if [[ -n "$startup_time" ]]; then
       check "Shell startup time" "pass"
     else

package/scripts/diagnostics/mcp-doctor.sh

@@ -77,12 +77,14 @@ log_success() {
   if [[ "$JSON_MODE" -ne 1 ]]; then
     ui_ok "$1" "${2:-}"
   fi
+  return 0
 }
 log_fail() {
   if [[ "$JSON_MODE" -ne 1 ]]; then
     ui_err "$1" "${2:-}"
   fi
   Errors=$((Errors + 1))
+  return 0
 }
 log_warn() {
   if [[ "$JSON_MODE" -ne 1 ]]; then
@@ -91,6 +93,7 @@ log_warn() {
   Warnings=$((Warnings + 1))
   # In strict mode, warnings become errors
   [[ "$STRICT_MODE" -eq 1 ]] && Errors=$((Errors + 1))
+  return 0
 }
 
 MCP_CONFIG="${MCP_CONFIG:-$HOME/.config/claude/mcp_servers.json}"

package/scripts/diagnostics/secret-governance.sh

@@ -13,7 +13,13 @@ STRICT="${DOTFILES_ALIAS_STRICT_MODE:-${DOTFILES_SECRETS_STRICT_MODE:-0}}"
 
 cd "$REPO_ROOT"
 
-mapfile -t staged_files < <(git diff --cached --name-only --diff-filter=ACM || true)
+# Portable read — `mapfile` is bash 4 only, and this runs from the
+# pre-commit hook on macOS where /bin/bash is 3.2. Without this the
+# hook exits 127 and the secret scan is skipped entirely.
+staged_files=()
+while IFS= read -r _line; do
+  [[ -n "$_line" ]] && staged_files+=("$_line")
+done < <(git diff --cached --name-only --diff-filter=ACM || true)
 if [[ "${#staged_files[@]}" -eq 0 ]]; then
   echo "Secret governance: no staged files."
   exit 0

package/scripts/diagnostics/security-score.sh

@@ -171,13 +171,20 @@ check_encryption() {
     add_points "encryption" 0 5 "SOPS secrets manager"
   fi
 
-  # GPG available
+  # Signing key material: this repo uses SSH ED25519 signing by default, with
+  # GPG still accepted for users who prefer it.
+  local signing_format signing_key
+  signing_format="$(git config --global gpg.format 2>/dev/null || true)"
+  signing_key="$(git config --global user.signingkey 2>/dev/null || true)"
+  signing_key="${signing_key/#\~/$HOME}"
   if command -v gpg >/dev/null 2>&1 && gpg --list-secret-keys 2>/dev/null | grep -q sec; then
-    add_points "encryption" 10 10 "GPG keys configured"
+    add_points "encryption" 10 10 "Signing key configured (GPG)"
+  elif [[ "$signing_format" == "ssh" && -n "$signing_key" && -f "$signing_key" ]]; then
+    add_points "encryption" 10 10 "Signing key configured (SSH)"
   elif command -v gpg >/dev/null 2>&1; then
-    add_points "encryption" 3 10 "GPG keys configured"
+    add_points "encryption" 3 10 "Signing key configured"
   else
-    add_points "encryption" 0 10 "GPG keys configured"
+    add_points "encryption" 0 10 "Signing key configured"
   fi
 }
 
@@ -286,6 +293,8 @@ check_system() {
   if [[ "$(uname)" == "Darwin" ]]; then
     if fdesetup status 2>/dev/null | grep -q "FileVault is On"; then
       add_points "system" 10 10 "Disk encryption (FileVault)"
+    elif diskutil apfs list 2>/dev/null | grep -q "FileVault:[[:space:]]*Yes"; then
+      add_points "system" 10 10 "Disk encryption (APFS FileVault)"
     else
       add_points "system" 0 10 "Disk encryption (FileVault)"
     fi
@@ -323,7 +332,7 @@ check_secrets() {
     local secrets_found=false
     local match=""
     # Check for common secret patterns, ignore templates/placeholders and variable expansions.
-    match=$(grep -rE "(api_key|api_secret|password|token)[[:space:]]*=[[:space:]]*['\"][^'\"]+['\"]" \
+    match=$(grep -rE "^[[:space:]]*(export[[:space:]]+)?[A-Za-z_]*(api_key|api_secret|password|token)[A-Za-z_]*[[:space:]]*=[[:space:]]*['\"][^'\"]+['\"]" \
       "${HOME}/.dotfiles" --include="*.sh" --include="*.zsh" --include="*.toml" 2>/dev/null |
       grep -v "example\\|template\\|placeholder" | grep -F -v "\${" | head -1 || true)
     if [[ -n "$match" ]]; then

package/scripts/diagnostics/verify_state.sh

@@ -12,6 +12,8 @@ set -euo pipefail
 echo " Starting Final Environment Verification..."
 
 Errors=0
+ALIASES_CONFIG="$HOME/.config/shell/aliases.sh"
+AliasesConfigReported=0
 
 check_file() {
   if [[ ! -f "$1" ]]; then
@@ -23,7 +25,13 @@ check_file() {
 }
 
 check_alias_in_config() {
-  if ! grep -q "$1" "$HOME/.config/shell/aliases.sh"; then
+  if [[ ! -f "$ALIASES_CONFIG" ]]; then
+    if [[ "$AliasesConfigReported" -eq 0 ]]; then
+      echo " Missing aliases config: $ALIASES_CONFIG"
+      Errors=$((Errors + 1))
+      AliasesConfigReported=1
+    fi
+  elif ! grep -q "$1" "$ALIASES_CONFIG"; then
     echo " Missing alias definition '$1' in built config"
     Errors=$((Errors + 1))
   else

package/scripts/dot/commands/ai.sh

@@ -5,7 +5,7 @@
 ##
 ## Provides AI CLI status, setup, RAG query, and bridge commands.
 ## Wraps AI CLI tools with contextual patterns and system metadata.
-## Usage: dot ai [delegate|cost|dashboard|proxy|local|status]|ai-setup|ai-query|cl|copilot|agy|kiro|sgpt|ollama|opencode|aider|autohand|vibe|qwen|zai
+## Usage: dot ai [delegate|cost|dashboard|proxy|local|status]|ai-setup|ai-query|cl|copilot|kimi|agy|kiro|sgpt|ollama|opencode|aider|autohand|vibe|qwen|zai
 
 set -euo pipefail
 
@@ -36,7 +36,7 @@ _show_ai_bridge_usage() {
   echo "       dot ai <tool> --style <name> \"<prompt>\""
   echo "       dot ai chat [tool]             # interactive session"
   echo ""
-  echo "Tools: cl codex copilot goose crush amp cursor-agent grok agy kiro sgpt ollama opencode aider autohand vibe qwen zai"
+  echo "Tools: cl codex copilot goose crush amp cursor-agent grok kimi agy kiro sgpt ollama opencode aider autohand vibe qwen zai"
   echo ""
   echo "Available styles:"
   # shellcheck disable=SC2012
@@ -69,21 +69,13 @@ _ai_refresh_status_cache() {
 
   local total=${#ai_entries[@]}
 
-  # Cold-cache refresh runs `$bin --version` for every tool — node-
-  # based ones are slow to start, so the total can hit 15-30s. Show a
-  # spinner so the user has feedback.
+  # Cold-cache refresh can take 15-30s across node-based tools; show progress.
   ui_spinner_start "Probing $total AI tools (cached for ${AI_STATUS_TTL}s)"
 
   local jobs="${DOTFILES_AI_PROBE_JOBS:-$(nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || echo 4)}"
   local probe_dir
   probe_dir="$(mktemp -d)"
 
-  # Probe via xargs -P. The probe logic lives INLINE in the bash -c
-  # string rather than as an exported function, because `export -f`
-  # doesn't always survive across bash invocations on every platform
-  # (notably macOS bash 3.2 needs the BASH_FUNC_*() env-var format,
-  # which subtly breaks for some shells in PATH). Inlining sidesteps
-  # the inheritance question entirely.
   local i=0
   local entry
   local indexed=()
@@ -98,6 +90,8 @@ _ai_refresh_status_cache() {
   # shellcheck disable=SC2016
   local _TO=""
   command -v timeout >/dev/null 2>&1 && _TO="timeout 8 "
+  # Variables expand inside the child Bash probe.
+  # shellcheck disable=SC2016
   local probe_script='
     payload="$1"; out_dir="$2"; to="$3"
     i="${payload%%|*}"; entry="${payload#*|}"
@@ -110,14 +104,7 @@ _ai_refresh_status_cache() {
       printf "%s\t0\t\n" "$bin" >"$out_dir/$i"
     fi
   '
-  # NOTE: `-I{}` already implies one input line per invocation. Adding
-  # `-n1` on top triggers a BSD-xargs quirk where the input line is
-  # word-split on whitespace ("0|Agents (autonomous)|..." → multiple
-  # entries). Use only `-I{}`.
-  #
-  # ALSO: feed null-delimited records (`-0`) so apostrophes and
-  # other quote-like characters in the descriptions ("Block's coding
-  # agent") don't trigger xargs's "unterminated quote" parser.
+  # Use only `-I{}` and null records for BSD xargs and quote-safe descriptions.
   printf '%s\0' "${indexed[@]}" |
     xargs -0 -I{} -P"$jobs" \
       bash -c "$probe_script" _ {} "$probe_dir" "$_TO" \
@@ -130,12 +117,7 @@ _ai_refresh_status_cache() {
   done
   rm -rf "$probe_dir"
 
-  # Guard with `|| true` because ui_spinner_stop's last line evaluates
-  # to rc=1 when stdout is a TTY (the `[[ ! -t 1 ]] && printf` short-
-  # circuit). Under `set -euo pipefail` that rc would kill the script
-  # right before we get to write the cache, leaving the user with a
-  # silent broken cold-cache run. Defence in depth — the function
-  # now also has an explicit `return 0` upstream.
+  # Guard against older ui_spinner_stop implementations returning 1 on a TTY.
   ui_spinner_stop || true
 
   mv "$tmp_file" "$AI_STATUS_CACHE_FILE"
@@ -145,10 +127,6 @@ _ai_get_cached_status() {
   cat "$AI_STATUS_CACHE_FILE"
 }
 
-# Look up field $2 (2=present 0/1, 3=version) for binary $1 from the
-# cached TSV. Replaces a bash-4 associative array for macOS bash 3.2.
-# (Removed _ai_status_field — cmd_ai_status now reads both fields in one awk.)
-
 # _ai_mise_pkg (binary -> mise package map) is defined in lib/dot/ai-install.sh.
 
 cmd_ai_status() {
@@ -164,6 +142,7 @@ cmd_ai_status() {
     "Agents (autonomous)|agent|Amp|amp|Sourcegraph's agentic coder"
     "Agents (autonomous)|agent|Cursor CLI|cursor-agent|Cursor's terminal agent"
     "Agents (autonomous)|agent|Grok Build|grok|xAI's terminal coding agent"
+    "Agents (autonomous)|agent|Kimi CLI|kimi|Moonshot AI's terminal coding agent"
     "Coding (interactive)|coding|Aider|aider|Git-aware AI pair programmer"
     "Coding (interactive)|coding|OpenCode|opencode|Open-source terminal coding agent"
     "Coding (interactive)|coding|Autohand Code|autohand|Autonomous multi-file coding agent"
@@ -278,6 +257,10 @@ cmd_ai_status() {
             install_grok_native "$name"
             continue
             ;;
+          kimi)
+            install_kimi_native "$name"
+            continue
+            ;;
         esac
         local pkg
         pkg=$(_ai_mise_pkg "$bin")
@@ -437,7 +420,12 @@ ${prompt}"
       fi
     elif [[ "$tool_bin" == "agy" ]]; then
       ui_warn "$tool" "not installed"
-      ui_info "Install" "curl -fsSL -o /tmp/agy-install.sh https://antigravity.google/cli/install.sh && bash /tmp/agy-install.sh"
+      ui_info "Install" "dot ai install agy (checksum verified)"
+      exit 1
+    elif [[ "$tool_bin" == "kimi" ]]; then
+      ui_warn "$tool" "not installed"
+      ui_info "Install" "dot ai install kimi"
+      ui_info "PATH" "Kimi Code installs to ~/.kimi-code/bin; restart your shell after install"
       exit 1
     else
       ui_err "$tool" "not installed and mise not available"
@@ -478,6 +466,27 @@ ${prompt}"
 
 # Dispatch — flat, verb-first surface (see docs/AI.md).
 case "${1:-}" in
+  --help | -h | help)
+    cat <<'EOF'
+Usage: ai.sh <command> [args...]
+
+Commands:
+  ai, ai-setup, ai-query, cl, claude, codex, copilot, goose, crush, amp,
+  cursor-agent, grok, kimi, agy, kiro, sgpt, ollama, opencode, aider, autohand,
+  vibe, qwen, zai
+EOF
+    ;;
+  "")
+    cat <<'EOF'
+Usage: ai.sh <command> [args...]
+
+Commands:
+  ai, ai-setup, ai-query, cl, claude, codex, copilot, goose, crush, amp,
+  cursor-agent, grok, kimi, agy, kiro, sgpt, ollama, opencode, aider, autohand,
+  vibe, qwen, zai
+EOF
+    exit 1
+    ;;
   ai)
     shift
     case "${1:-}" in
@@ -565,7 +574,7 @@ case "${1:-}" in
     shift
     cmd_ai_query "$@"
     ;;
-  cl | claude | codex | copilot | goose | crush | amp | cursor-agent | grok | agy | kiro | sgpt | ollama | opencode | aider | autohand | vibe | qwen | zai)
+  cl | claude | codex | copilot | goose | crush | amp | cursor-agent | grok | kimi | agy | kiro | sgpt | ollama | opencode | aider | autohand | vibe | qwen | zai)
     _ai_deprecated "dot ai $1"
     tool="$1"
     shift

package/scripts/dot/commands/aliases.sh

@@ -133,12 +133,36 @@ cmd_aliases() {
       rm -f "$tmp_aliases"
       ;;
     cheatsheet)
+      # Destination defaults to the checkout's docs/ but can be
+      # redirected with `--output PATH` (or `-` for stdout). The
+      # hardcoded path made this the one subcommand that could not be
+      # exercised without writing into the working tree:
+      # require_source_dir() resolves from the location of the lib that
+      # was sourced, so it always pointed at the real repo no matter
+      # how the sandbox redirected $HOME/.dotfiles.
       ui_header "Alias Cheatsheet"
-      local src_dir out
+      local src_dir out=""
       src_dir="$(require_source_dir)"
-      out="$src_dir/docs/ALIASES_CHEATSHEET.md"
-      bash "$src_dir/scripts/diagnostics/aliases-cheatsheet.sh" >"$out"
-      ui_ok "Generated" "$out"
+      while (($#)); do
+        case "$1" in
+          --output | -o)
+            out="${2:-}"
+            [[ -n "$out" ]] || die "Usage: dot aliases cheatsheet [--output PATH|-]"
+            shift 2
+            ;;
+          *)
+            die "Unknown option for cheatsheet: $1"
+            ;;
+        esac
+      done
+      out="${out:-$src_dir/docs/ALIASES_CHEATSHEET.md}"
+      if [[ "$out" == "-" ]]; then
+        bash "$src_dir/scripts/diagnostics/aliases-cheatsheet.sh"
+      else
+        mkdir -p "$(dirname "$out")"
+        bash "$src_dir/scripts/diagnostics/aliases-cheatsheet.sh" >"$out"
+        ui_ok "Generated" "$out"
+      fi
       ;;
     tiers)
       local profile ecosystems security_mode dangerous buckets

package/scripts/dot/commands/appearance.sh

@@ -12,6 +12,15 @@ source "$SCRIPT_DIR/../../../lib/dot/utils.sh"
 
 dot_ui_command_banner "Appearance" "${1:-}"
 
+usage() {
+  cat <<'EOF'
+Usage: appearance.sh <command> [args...]
+
+Commands:
+  theme, wallpaper, fonts, tune
+EOF
+}
+
 cmd_theme() {
   run_script "scripts/theme/switch.sh" "Theme switcher" "$@"
 }
@@ -71,6 +80,13 @@ cmd_tune() {
 
 # Dispatch
 case "${1:-}" in
+  --help | -h | help)
+    usage
+    ;;
+  "")
+    usage
+    exit 1
+    ;;
   theme)
     shift
     cmd_theme "$@"

package/scripts/dot/commands/core.sh

@@ -34,6 +34,16 @@ if [[ "${1:-}" != "cd" ]]; then
   dot_ui_command_banner "Core" "${1:-}"
 fi
 
+usage() {
+  cat <<'EOF'
+Usage: core.sh <command> [args...]
+
+Commands:
+  apply, sync, update, add, diff, status, remove, cd, edit, commit,
+  clean-cache, uninstall
+EOF
+}
+
 cmd_apply() {
   local src_dir
   src_dir="$(resolve_source_dir)"
@@ -145,6 +155,13 @@ cmd_clean_cache() {
 
 # Dispatch
 case "${1:-}" in
+  --help | -h | help)
+    usage
+    ;;
+  "")
+    usage
+    exit 1
+    ;;
   apply)
     shift
     cmd_apply "$@"

package/scripts/dot/commands/diagnostics.sh

@@ -13,6 +13,18 @@ source "$SCRIPT_DIR/../../../lib/dot/utils.sh"
 
 dot_ui_command_banner "Diagnostics" "${1:-}" "$@"
 
+usage() {
+  cat <<'EOF'
+Usage: diagnostics.sh <command> [args...]
+
+Commands:
+  doctor, heal, health, security-score, scorecard, perf, conflicts, locks,
+  snapshot, attest, rollback, drift, history, benchmark, verify, restore,
+  load-bench, load-bench-pty, chaos, teleport, secret-audit, bundle, metrics,
+  smoke-test, intelligence
+EOF
+}
+
 cmd_doctor() {
   local src_dir
   src_dir="$(resolve_source_dir)"
@@ -139,6 +151,13 @@ cmd_metrics() {
 
 # Dispatch
 case "${1:-}" in
+  --help | -h | help)
+    usage
+    ;;
+  "")
+    usage
+    exit 1
+    ;;
   doctor)
     shift
     cmd_doctor "$@"

package/scripts/dot/commands/fleet.sh

@@ -73,7 +73,7 @@ _fleet_emit_event() {
     endpoint="$(sed -n 's/^endpoint = "\(.*\)"/\1/p' "$data_file" | head -1)"
   fi
   if [[ -n "$endpoint" ]] && [[ "$endpoint" == https://* ]]; then
-    curl -fsSL -X POST -H "Content-Type: application/json" \
+    curl --proto '=https' --tlsv1.2 -fsSL -X POST -H "Content-Type: application/json" \
       -d "$payload" "$endpoint" >/dev/null 2>&1 || true
   fi
 }

package/scripts/dot/commands/manual.sh

@@ -67,7 +67,7 @@ resolve_source() {
       echo "$src_dir/$fname"
       return 0
     fi
-    ui_err "manual" "local build not found at $src_dir/$fname — run bash tools/docs/build-manual.sh"
+    ui_err "manual" "local build not found at $src_dir/$fname — run bash tools/docs/build-manual.sh" >&2
     return 1
   fi
 
@@ -76,7 +76,7 @@ resolve_source() {
       echo "$OFFLINE_DIR/$fname"
       return 0
     fi
-    ui_err "manual" "offline copy not found at $OFFLINE_DIR/$fname"
+    ui_err "manual" "offline copy not found at $OFFLINE_DIR/$fname" >&2
     return 1
   fi
 
@@ -84,9 +84,9 @@ resolve_source() {
   if [[ ! -f "$cache_path" ]] || [[ $(find "$cache_path" -mtime +7 -print 2>/dev/null | wc -l) -gt 0 ]]; then
     mkdir -p "$(dirname "$cache_path")"
     local url="$MANUAL_URL/$fname"
-    ui_info "manual" "fetching $url"
+    ui_info "manual" "fetching $url" >&2
     if ! curl -fsSL "$url" -o "$cache_path"; then
-      ui_err "manual" "failed to download $url"
+      ui_err "manual" "failed to download $url" >&2
       return 1
     fi
   fi

package/scripts/dot/commands/meta.sh

@@ -30,30 +30,88 @@ meta_banner_section() {
 
 dot_ui_command_banner "$(meta_banner_section "${1:-}")" "${1:-}" "$@"
 
+# Last meaningful line of a captured log, used as a step's `ok` detail.
+# Collapses carriage-return progress (git/nvim spam \r), strips ANSI,
+# takes the last non-empty line, and clips it so the rendered step stays
+# on one line.
+_upgrade_last_line() {
+  tr '\r' '\n' <"$1" 2>/dev/null |
+    sed -E 's/\x1b\[[0-9;?]*[a-zA-Z]//g' |
+    awk 'NF{last=$0} END{print last}' |
+    cut -c1-56
+}
+
 cmd_upgrade() {
   local src_dir
   src_dir="$(require_source_dir)"
 
+  # Per-step logs. Each phase's stdout+stderr is captured here rather
+  # than streamed to the terminal: the git/nvim/chezmoi output is noisy
+  # (carriage-return progress bars, remote counters) and, in rich mode,
+  # writing it to the terminal corrupts the dot-ui renderer that owns
+  # the screen. Failing steps get their tail dumped after the run.
+  local log_dir
+  log_dir="$(mktemp -d "${TMPDIR:-/tmp}/dot-upgrade.XXXXXX")"
+  local fail_labels=() fail_logs=()
+
+  # _upgrade_step <id> <label> <running-detail> -- cmd [args...]
+  # Renders one tracked step: spinner while it runs, then ok (with the
+  # log's last line) or fail. Never aborts the run — a failed phase is
+  # recorded and surfaced at the end, matching the previous `|| true`
+  # behaviour but without the raw flood.
+  _upgrade_step() {
+    local id="$1" label="$2" running="$3"
+    shift 3
+    [[ "${1:-}" == "--" ]] && shift
+    local log="$log_dir/$id.log" rc=0
+    ui_step "$id" "$label" run "$running"
+    "$@" >"$log" 2>&1 || rc=$?
+    if [[ "$rc" -eq 0 ]]; then
+      ui_step "$id" "" ok "$(_upgrade_last_line "$log")"
+    else
+      ui_step "$id" "" fail "exited $rc"
+      fail_labels+=("$label")
+      fail_logs+=("$log")
+    fi
+    return 0
+  }
+
+  ui_steps_begin "Upgrade" ""
+
   if [ -f "$src_dir/nix/flake.nix" ] && has_command nix; then
-    ui_info "Updating Nix flake"
-    (cd "$src_dir" && nix flake update) || true
-    ui_info "Running Nix garbage collection"
-    nix-collect-garbage -d || true
+    _upgrade_step nix-flake "Nix flake" "updating…" -- \
+      sh -c 'cd "$1" && nix flake update' _ "$src_dir"
+    _upgrade_step nix-gc "Nix GC" "collecting…" -- nix-collect-garbage -d
   fi
 
-  ui_info "Updating dotfiles"
-  chezmoi update || true
+  _upgrade_step dotfiles "Dotfiles" "chezmoi update…" -- chezmoi update
 
   if has_command nvim; then
-    ui_info "Updating Neovim plugins"
-    nvim --headless "+Lazy! sync" +qa || true
+    _upgrade_step nvim "Neovim plugins" "Lazy sync…" -- \
+      nvim --headless "+Lazy! sync" +qa
   fi
 
-  if [ "${DOTFILES_FONTS:-}" = "1" ]; then
-    if [ -f "$src_dir/scripts/fonts/install-nerd-fonts.sh" ]; then
-      ui_info "Installing Nerd Fonts"
+  if [ "${DOTFILES_FONTS:-}" = "1" ] &&
+    [ -f "$src_dir/scripts/fonts/install-nerd-fonts.sh" ]; then
+    _upgrade_step fonts "Nerd Fonts" "installing…" -- \
       sh "$src_dir/scripts/fonts/install-nerd-fonts.sh"
-    fi
+  fi
+
+  local n=${#fail_labels[@]}
+  if [[ "$n" -eq 0 ]]; then
+    ui_steps_end "toolchains, plugins, and dotfiles up to date"
+    rm -rf "$log_dir"
+  else
+    ui_steps_end "$n step(s) failed"
+    # Surfaced after ui_steps_end so the rich renderer has torn down —
+    # printing mid-render would garble the display.
+    local i=0
+    while ((i < n)); do
+      ui_err "${fail_labels[$i]}" "log tail:"
+      tail -n 15 "${fail_logs[$i]}" | sed 's/^/    /'
+      ((i++)) || true
+    done
+    ui_info "Logs" "$log_dir"
   fi
 }
 
@@ -251,6 +309,23 @@ case "${1:-}" in
     shift
     cmd_mode "$@"
     ;;
+  --help | -h | help)
+    cat <<'EOF'
+Usage: meta.sh <command> [args...]
+
+Commands:
+  cache-refresh, prewarm, docs, learn, keys, sandbox, mcp, mode, agent
+EOF
+    ;;
+  "")
+    cat <<'EOF'
+Usage: meta.sh <command> [args...]
+
+Commands:
+  cache-refresh, prewarm, docs, learn, keys, sandbox, mcp, mode, agent
+EOF
+    exit 1
+    ;;
   *)
     echo "Unknown meta command: ${1:-}" >&2
     exit 1