@sebastienrousseau/dotfiles 0.2.501 → 0.2.503

package/scripts/README.md

@@ -0,0 +1,123 @@
+# `scripts/` — Framework Code
+
+Everything in this directory is **framework code**. Nothing here
+deploys to `~/`; chezmoi ignores the whole tree (see
+`.chezmoiignore`). Scripts are invoked by the `dot` CLI, by CI
+workflows, by `chezmoi apply` hooks, or by hand.
+
+## Subtree map
+
+Per the v0.2.503 reorg (RFC `docs/operations/RFC_v0_2_503_reorganization.md`),
+**repo-only ops** (CI, release, maintenance, docs-generation) have
+moved to the top-level `tools/` tree. `scripts/` retains the
+**runtime-invoked** scripts that the `dot` CLI dispatches to plus a
+few specialised subtrees.
+
+### `scripts/` (CLI dispatch + specialised subtrees)
+
+| Path | Purpose | Touched by |
+|---|---|---|
+| `scripts/dot/commands/` | Per-subcommand handlers for the `dot` CLI. Sources `lib/dot/*.sh` (moved out of this tree in v0.2.503 Phase 1). | Dispatched by `bin/dot` |
+| `scripts/dot/powershell/` | Native PowerShell module (`Dot.psm1`) exporting `Get-DotVersion` / `Invoke-DotHelp` / `Test-DotAgentsSync`. | `bin/dot.ps1` |
+| `scripts/dot/data/` | Per-command static data (registry seeds, palette tables). | `scripts/dot/commands/*` |
+| `scripts/lib/` | Cross-cutting library helpers reused across multiple scripts. Example: `secrets_provider.sh` (keychain / pass / age dispatch). | `scripts/dot/commands/*`, ops scripts |
+| `scripts/diagnostics/` | `doctor.sh` and its helpers — long-form environment health check. | `dot doctor` |
+| `scripts/security/` | Security-domain ops: `check-disclosure-key-expiry.sh`, `lock-configs.sh`, etc. | `dot security`, CI |
+| `scripts/secrets/` | Secret-bucket utilities (rotation, audit). | `dot secrets` subcommands |
+| `scripts/theme/` | Wallpaper-to-palette extraction logic. | `dot theme rebuild` |
+| `scripts/tools/` | Tool-helpers shipped via `dot tools` (e.g. `cmatrix.sh`, `emoji-picker.sh`, `figlet-banner.sh`, `log-rotate.sh`). Runtime-invoked. | `dot tools`, `dot env` |
+| `scripts/tuning/` | Opt-in OS tuning scripts (`macos.sh`, `linux.sh`). | `dot tune`, manual invocation |
+| `scripts/ops/` | Repo-wide ops: `rollback.sh`, etc. | `dot rollback`, maintenance |
+| `scripts/fonts/` | Nerd Font install helpers. | `dot fonts` |
+| `scripts/git-hooks/` | Git hooks not managed by chezmoi (kept here for portable install). | `install/provision/*` |
+| `scripts/qa/` | Quality-assurance helpers (PowerShell contract tests, version-consistency checks, scorecard snapshot, etc). | `.github/workflows/pr-signature.yml`, `powershell-contract.yml`, doc-drift |
+| `scripts/demo/` | Demonstration helpers (recordings, screenshots). | Manual |
+| `scripts/version-sync.sh` | Bulk version-string propagator (`scripts/qa/check-version-consistency.sh` is the verifier). | Release flow |
+| `scripts/uninstall.sh` | Reverse-of-`install.sh` — user-invoked. | Manual |
+
+### `tools/` (repo-only ops, not distributable)
+
+| Path | Purpose | Touched by |
+|---|---|---|
+| `tools/ci/` | CI-only helpers: `dot-cli-startup-bench.sh`, `install-chezmoi-verified.sh`, `windows-smoke-test.ps1`, `run-coverage.sh`, etc. | `.github/workflows/*` |
+| `tools/release/` | Release-time tasks. | Release workflow |
+| `tools/maintenance/` | Recurring upkeep: `check-updates.sh`, etc. | Cron, manual |
+| `tools/docs/` | Documentation-generation helpers (manual builds, screenshot CI, `generate-command-index.sh`). | `manual-publish.yml`, `dot manual`, doc-drift |
+
+## `scripts/dot/` breakdown
+
+The `dot` CLI is implemented as `bin/dot`
+(dispatcher) + `scripts/dot/commands/<cmd>.sh` (per-command
+handlers) + `lib/dot/*.sh` (shared helpers — moved out of
+`scripts/dot/lib/` in v0.2.503 Phase 1 per the
+[reorganisation RFC](../docs/operations/RFC_v0_2_503_reorganization.md)).
+
+| Path | Purpose |
+|---|---|
+| `scripts/dot/commands/` | One file per `dot <cmd>` subcommand. Each defines a `cmd_<name>()` function the dispatcher calls. Sources the library via `$SCRIPT_DIR/../../../lib/dot/<X>.sh`. |
+| `scripts/dot/powershell/` | Native PowerShell module — see top-level table. |
+| **`lib/dot/utils.sh`** | Common helpers (resolve_source_dir, validate_name, die, run_script, etc.). |
+| **`lib/dot/ui.sh`** | Single source of truth for CLI output (ui_ok/warn/err/info, ui_header, ui_table_*, ui_spinner_*, ui_confirm, ...). |
+| **`lib/dot/platform.sh`** | OS / shell / WSL detection, path translation. |
+| **`lib/dot/log.sh`** | Structured logging (JSONL audit log when `DOTFILES_AUDIT_LOG=1`). |
+| **`lib/dot/bento.sh`** | The "bento box" layout primitive used by `dot health` and friends. |
+
+## Adding a new subcommand
+
+1. Create `scripts/dot/commands/<name>.sh`:
+
+   ```bash
+   #!/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=../lib/utils.sh
+   source "$SCRIPT_DIR/../lib/utils.sh"
+
+   dot_ui_command_banner "<Title>" "${1:-}"
+
+   cmd_<name>() {
+     # ...
+   }
+
+   cmd_<name>_help() {
+     cat <<-EOF
+     Usage: dot <name> [args]
+     # ...
+   EOF
+   }
+   ```
+
+2. Add a dispatch arm in `bin/dot`:
+
+   ```bash
+   <name>) load_commands "<name>"; cmd_<name> "$@" ;;
+   ```
+
+3. Document it in `docs/manual/03-reference/01-dot-cli.md` and add
+   to `docs/manual/command-index.md`.
+
+4. Add a help-table entry in `bin/dot`'s
+   help renderer.
+
+5. Add a unit test under `tests/unit/<domain>/test_<name>.sh`
+   (run with `./tests/framework/test_runner.sh`).
+
+## Conventions
+
+- **Shell style**: 2-space indent, `set -euo pipefail`, shellcheck-clean
+  with the project's flags (`--severity=error -e SC1091 -e SC2030 -e SC2031`).
+- **Formatting**: `shfmt -i 2 -ci`.
+- **Output**: NEVER `printf` raw ANSI. Source `scripts/dot/lib/ui.sh`
+  and use `ui_ok`, `ui_table_*`, etc.
+- **Exit codes**: 1 = bad usage, 2 = no provider / dependency missing,
+  3 = empty result / not found, ≥4 = provider-specific. Document
+  per-command in the help text.
+- **Validation**: Always `validate_name "$arg" "tool name"` before
+  passing user input to `mise`, `gh`, `ssh`, etc.
+
+## See also
+
+- `../docs/STRUCTURE.md` — full repository map.
+- `docs/manual/03-reference/01-dot-cli.md` — every `dot <cmd>` documented.
+- `scripts/dot/lib/ui.sh` — the UI primitive library (always source this for output).

package/scripts/ci/check-copyright-headers.sh

@@ -1,96 +1,7 @@
 #!/usr/bin/env bash
 # Copyright (c) 2015-2026 Dotfiles. All rights reserved.
-# Copyright header validator (zero-tolerance policy).
-#
-# Scans source files for a copyright header in the first 10 lines. Patterns
-# are deliberately narrow to avoid false positives on C-style `(c)` comments
-# or the word "token" appearing in running text.
-#
-# Usage:
-#   check-copyright-headers.sh [--extensions=sh,lua,nix,...] [--excludes=REGEX]
-#
-# Exit codes:
-#   0  all files have a valid header
-#   1  one or more files are missing a header
-#   2  invalid invocation
-
+# Compat shim: the canonical script moved to tools/ci/ in v0.2.503.
+# Pinned reusable workflows on master still reference the old path;
+# this delegates so they keep working until the next pin bump.
 set -euo pipefail
-
-EXTENSIONS_DEFAULT="sh,lua,nix,py,js,ts,go,rs,java,cpp,c,h,hpp"
-EXCLUDES_DEFAULT='(^|/)(node_modules|\.git|vendor|target|build)/|\.tmpl$|(^|/)\.chezmoitemplates/'
-
-EXTENSIONS="$EXTENSIONS_DEFAULT"
-EXCLUDES="$EXCLUDES_DEFAULT"
-
-for arg in "$@"; do
-  case "$arg" in
-    --extensions=*) EXTENSIONS="${arg#*=}" ;;
-    --excludes=*) EXCLUDES="${arg#*=}" ;;
-    -h | --help)
-      sed -n '2,14p' "$0" | sed 's/^# \{0,1\}//'
-      exit 0
-      ;;
-    *)
-      echo "Unknown argument: $arg" >&2
-      exit 2
-      ;;
-  esac
-done
-
-# Narrow patterns — each must be specific enough that running prose cannot match.
-# Deliberately DROPPED: bare "(c) " (false-positives in C comments),
-# bare "All rights reserved" (often appears in vendored prose).
-# Matched by `grep -F`, so these are literal strings.
-PATTERNS=(
-  "Copyright (c)"
-  "Copyright ©"
-  "SPDX-License-Identifier:"
-  "© "
-)
-
-# Build a ripgrep glob like `{*.sh,*.lua,*.nix}` from the comma list.
-IFS=',' read -r -a exts <<<"$EXTENSIONS"
-glob="{"
-for i in "${!exts[@]}"; do
-  [[ $i -gt 0 ]] && glob+=","
-  glob+="*.${exts[$i]}"
-done
-glob+="}"
-
-mapfile -t all_files < <(rg --files -g "$glob" 2>/dev/null || true)
-
-if [[ "${#all_files[@]}" -eq 0 ]]; then
-  echo "::notice::No files matched extensions: $EXTENSIONS"
-  exit 0
-fi
-
-missing=()
-for file in "${all_files[@]}"; do
-  if [[ "$file" =~ $EXCLUDES ]]; then
-    continue
-  fi
-
-  found=false
-  # Read the first 10 lines once; search each pattern against that buffer.
-  head_buf="$(head -n 10 "$file" 2>/dev/null || true)"
-  for pattern in "${PATTERNS[@]}"; do
-    if grep -qF -- "$pattern" <<<"$head_buf"; then
-      found=true
-      break
-    fi
-  done
-
-  $found || missing+=("$file")
-done
-
-if [[ "${#missing[@]}" -gt 0 ]]; then
-  echo "::error::Copyright header validation failed — ${#missing[@]} file(s) missing header"
-  echo "Files missing a recognised copyright header:"
-  printf '  - %s\n' "${missing[@]}"
-  echo
-  echo "Add ONE of the following to the first 10 lines:"
-  printf '  - %s\n' "${PATTERNS[@]}"
-  exit 1
-fi
-
-echo "::notice::All ${#all_files[@]} file(s) have a valid copyright header"
+exec bash "$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)/tools/ci/check-copyright-headers.sh" "$@"

package/scripts/ci/check-shell-preamble.sh

@@ -1,106 +1,7 @@
 #!/usr/bin/env bash
 # Copyright (c) 2015-2026 Dotfiles. All rights reserved.
-# =============================================================================
-# check-shell-preamble.sh — Enforce `set -euo pipefail` (bash) / `set -eu` (sh)
-# on every executable shell script in the repo.
-#
-# Skip-rules:
-#   * Sourced libraries that declare themselves as such via a "Sourced by ..."
-#     header comment in the first 15 lines.
-#   * Explicit opt-out via `# preamble:skip` marker in the first 15 lines
-#     (used by completion files, init fragments, and other library code that
-#     is loaded into the caller's shell context).
-#   * Files under tests/ (the test runner sets shell options for its children).
-#
-# Invocation:
-#   * pre-commit local hook (files passed as args)
-#   * standalone: ./scripts/ci/check-shell-preamble.sh           # full repo
-#                 ./scripts/ci/check-shell-preamble.sh file.sh   # explicit
-# =============================================================================
-
+# Compat shim: the canonical script moved to tools/ci/ in v0.2.503.
+# Pinned reusable workflows on master still reference the old path;
+# this delegates so they keep working until the next pin bump.
 set -euo pipefail
-
-check_one() {
-  local f="$1"
-
-  [[ -f "$f" ]] || return 0
-
-  local shebang
-  shebang="$(head -1 "$f" 2>/dev/null || true)"
-
-  # Only check files with a bash or sh shebang.
-  case "$shebang" in
-    *bash*) ;;
-    *sh) ;;
-    *) return 0 ;;
-  esac
-
-  # Skip files declaring themselves as sourced libraries or opting out.
-  if head -15 "$f" | grep -Eq '^# *(Sourced by |preamble:skip|shellcheck source-only)'; then
-    return 0
-  fi
-
-  # Skip the test suite — tests are sourced by tests/framework/test_runner.sh
-  # which manages shell options for its children.
-  case "$f" in
-    tests/*) return 0 ;;
-    # Bulk-sourced fragments. These directories contain hundreds of
-    # alias / function / PATH snippets that are sourced into the
-    # caller's shell context — adding `set -e` locally would corrupt
-    # the caller. Path-skipped en masse rather than annotated per-file
-    # (would be 300+ marker comments).
-    .chezmoitemplates/aliases/*) return 0 ;;
-    .chezmoitemplates/functions/*) return 0 ;;
-    .chezmoitemplates/paths/*) return 0 ;;
-    # dot_config/shell/* and scripts/dot/lib/* are also sourced but
-    # have explicit `# Sourced by` headers as of #854 (defense in
-    # depth — the lint also accepts them on header alone).
-    dot_local/bin/executable_dot_completion) return 0 ;; # zsh completion, sourced into shell
-  esac
-
-  # Required preamble lives within the first 50 lines (after optional docstring).
-  local preamble_re
-  case "$shebang" in
-    *bash*)
-      preamble_re='^[[:space:]]*set[[:space:]]+-([eu]+o[[:space:]]+pipefail|euo[[:space:]]+pipefail|eu[[:space:]]*$)'
-      ;;
-    *sh)
-      preamble_re='^[[:space:]]*set[[:space:]]+-eu[o]?'
-      ;;
-  esac
-
-  if ! head -50 "$f" | grep -Eq "$preamble_re"; then
-    echo "MISSING preamble: $f"
-    return 1
-  fi
-}
-
-fail=0
-if [[ $# -gt 0 ]]; then
-  for f in "$@"; do
-    check_one "$f" || fail=1
-  done
-else
-  # Full-repo scan
-  while IFS= read -r f; do
-    check_one "$f" || fail=1
-  done < <(git ls-files | grep -E '\.sh$|^dot_local/bin/executable_|^scripts/.+\.sh$')
-fi
-
-if [[ $fail -ne 0 ]]; then
-  cat >&2 <<'MSG'
-
-Some shell scripts are missing the safety preamble.
-  * bash → `set -euo pipefail`
-  * sh   → `set -eu`
-
-If the file is a sourced library, add this header to its first 15 lines:
-  # Sourced by <parent>.sh; inherits set -euo pipefail
-
-If the file is a shell init fragment / completion that must NOT enforce its own
-options on the caller, add this marker instead:
-  # preamble:skip
-
-MSG
-  exit 1
-fi
+exec bash "$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)/tools/ci/check-shell-preamble.sh" "$@"

package/scripts/ci/guard-gitleaks-checkout.sh

@@ -1,57 +1,7 @@
 #!/usr/bin/env bash
 # Copyright (c) 2015-2026 Dotfiles. All rights reserved.
-# Guard against full-history gitleaks scans on manual runs.
-# This ensures workflow checkout remains shallow near gitleaks steps.
-
+# Compat shim: the canonical script moved to tools/ci/ in v0.2.503.
+# Pinned reusable workflows on master still reference the old path;
+# this delegates so they keep working until the next pin bump.
 set -euo pipefail
-
-check_workflow() {
-  local workflow="$1"
-  local failed=0
-  local line_no
-
-  while IFS=: read -r line_no _; do
-    local start end context
-    start=$((line_no - 16))
-    end=$((line_no + 2))
-    if [[ "$start" -lt 1 ]]; then
-      start=1
-    fi
-
-    context="$(sed -n "${start},${end}p" "$workflow")"
-
-    if [[ "$context" != *"actions/checkout"* ]]; then
-      echo "ERROR: $workflow:$line_no missing nearby checkout for gitleaks step."
-      failed=1
-      continue
-    fi
-
-    if [[ "$context" != *"fetch-depth: 1"* ]]; then
-      echo "ERROR: $workflow:$line_no gitleaks step must use checkout fetch-depth: 1."
-      failed=1
-    fi
-
-    if [[ "$context" == *"fetch-depth: 0"* ]]; then
-      echo "ERROR: $workflow:$line_no gitleaks step contains forbidden fetch-depth: 0."
-      failed=1
-    fi
-  done < <(grep -n "gitleaks/gitleaks-action" "$workflow" || true)
-
-  return "$failed"
-}
-
-main() {
-  local failed=0
-
-  check_workflow ".github/workflows/ci.yml" || failed=1
-  check_workflow ".github/workflows/security-enhanced.yml" || failed=1
-
-  if [[ "$failed" -ne 0 ]]; then
-    echo "Gitleaks checkout guard failed."
-    exit 1
-  fi
-
-  echo "Gitleaks checkout guard passed."
-}
-
-main "$@"
+exec bash "$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)/tools/ci/guard-gitleaks-checkout.sh" "$@"

package/scripts/diagnostics/a2a-conformance.sh

@@ -7,8 +7,8 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="${REPO_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
 
-# shellcheck source=../dot/lib/ui.sh
-source "$SCRIPT_DIR/../dot/lib/ui.sh"
+# shellcheck source=../../lib/dot/ui.sh
+source "$SCRIPT_DIR/../../lib/dot/ui.sh"
 
 JSON_MODE=0
 STRICT_MODE=0
@@ -35,8 +35,8 @@ command -v jq >/dev/null 2>&1 || {
 
 a2a_card="$REPO_ROOT/.well-known/agent-card.json"
 legacy_doc="$REPO_ROOT/.well-known/agent.json"
-internal_card="$REPO_ROOT/dot_config/dotfiles/agent-card.json"
-agent_profiles="$REPO_ROOT/dot_config/dotfiles/agent-profiles.json"
+internal_card="$REPO_ROOT/defaults/dot_config/dotfiles/agent-card.json"
+agent_profiles="$REPO_ROOT/defaults/dot_config/dotfiles/agent-profiles.json"
 status="healthy"
 issues=()
 

package/scripts/diagnostics/alias-governance.sh

@@ -110,7 +110,7 @@ if [[ -f "$deprecations_file" ]]; then
         alias_found=1
       fi
       function_found=0
-      if rg -q --glob '*.sh' --glob '*.aliases.sh' --glob '*.tmpl' "^[[:space:]]*(function[[:space:]]+)?${alias_name}[[:space:]]*\\(\\)" "$SCRIPT_DIR/../../.chezmoitemplates/aliases" "$SCRIPT_DIR/../../scripts/dot"; then
+      if rg -q --glob '*.sh' --glob '*.aliases.sh' --glob '*.tmpl' "^[[:space:]]*(function[[:space:]]+)?${alias_name}[[:space:]]*\\(\\)" "$SCRIPT_DIR/../../defaults/.chezmoitemplates/aliases" "$SCRIPT_DIR/../../scripts/dot"; then
         function_found=1
       fi
       if [[ $alias_found -eq 1 || $function_found -eq 1 ]]; then

package/scripts/diagnostics/aliases-cheatsheet.sh

@@ -3,9 +3,9 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-# shellcheck source=../dot/lib/utils.sh
+# shellcheck source=../../lib/dot/utils.sh
 # shellcheck disable=SC1091
-source "$SCRIPT_DIR/../dot/lib/utils.sh"
+source "$SCRIPT_DIR/../../lib/dot/utils.sh"
 
 src_dir="$(require_source_dir)"
 manifest="$src_dir/scripts/diagnostics/aliases-manifest.sh"

package/scripts/diagnostics/benchmark.sh

@@ -44,12 +44,12 @@ _cleanup_files=()
 trap 'rm -f "${_cleanup_files[@]}"' EXIT
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-# shellcheck source=../dot/lib/ui.sh
+# shellcheck source=../../lib/dot/ui.sh
 # shellcheck disable=SC1091
-source "$SCRIPT_DIR/../dot/lib/ui.sh"
-# shellcheck source=../dot/lib/log.sh
+source "$SCRIPT_DIR/../../lib/dot/ui.sh"
+# shellcheck source=../../lib/dot/log.sh
 # shellcheck disable=SC1091
-source "$SCRIPT_DIR/../dot/lib/log.sh"
+source "$SCRIPT_DIR/../../lib/dot/log.sh"
 export DOT_COMMAND="benchmark"
 
 BENCHMARK_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/dotfiles/benchmarks"

package/scripts/diagnostics/conflicts.sh

@@ -6,9 +6,9 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-# shellcheck source=../dot/lib/ui.sh
+# shellcheck source=../../lib/dot/ui.sh
 # shellcheck disable=SC1091
-source "$SCRIPT_DIR/../dot/lib/ui.sh"
+source "$SCRIPT_DIR/../../lib/dot/ui.sh"
 
 ui_init
 

package/scripts/diagnostics/doctor-unified.sh

@@ -8,9 +8,9 @@ trap 'rm -f "${_cleanup_files[@]}"' EXIT
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
-# shellcheck source=../dot/lib/ui.sh
+# shellcheck source=../../lib/dot/ui.sh
 # shellcheck disable=SC1091
-source "$SCRIPT_DIR/../dot/lib/ui.sh"
+source "$SCRIPT_DIR/../../lib/dot/ui.sh"
 ui_init
 
 passthrough=()

package/scripts/diagnostics/doctor.sh

@@ -19,15 +19,15 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-# shellcheck source=../dot/lib/ui.sh
+# shellcheck source=../../lib/dot/ui.sh
 # shellcheck disable=SC1091
-source "$SCRIPT_DIR/../dot/lib/ui.sh"
-# shellcheck source=../dot/lib/platform.sh
+source "$SCRIPT_DIR/../../lib/dot/ui.sh"
+# shellcheck source=../../lib/dot/platform.sh
 # shellcheck disable=SC1091
-source "$SCRIPT_DIR/../dot/lib/platform.sh"
-# shellcheck source=../dot/lib/log.sh
+source "$SCRIPT_DIR/../../lib/dot/platform.sh"
+# shellcheck source=../../lib/dot/log.sh
 # shellcheck disable=SC1091
-source "$SCRIPT_DIR/../dot/lib/log.sh"
+source "$SCRIPT_DIR/../../lib/dot/log.sh"
 export DOT_COMMAND="doctor"
 
 ui_init
@@ -548,9 +548,30 @@ fi
 # 2. Slow-init tools that are present but NOT wrapped in _cached_eval.
 # Each of these runs uncached on every shell start; common offenders eat
 # 100-500ms apiece on a populated dev machine.
+#
+# Only flag tools that actually emit shell init via `<tool> init <shell>`
+# (or equivalent) and would benefit from caching that output. Plain CLIs
+# like gh/cargo/pnpm/yarn don't have init eval; their completions are
+# cached separately under $ZSH_COMPLETIONS_DIR.
 unwrapped=""
-for tool in nvm fnm pyenv rbenv jenv asdf sdkman conda kubectl helm gh cargo pnpm yarn thefuck broot mcfly; do
+for tool in nvm fnm pyenv rbenv jenv asdf sdkman conda kubectl helm thefuck broot mcfly direnv; do
   command -v "$tool" >/dev/null 2>&1 || continue
+  # If the tool is installed but no shell config sources or evals its
+  # init (no `$tool env`, `$tool init`, `$tool.sh`, lazy-load stub), it
+  # isn't adding startup cost — skip the warning.
+  init_referenced=0
+  if grep -rIlqE "\\b${tool}([[:space:]]+(env|init|hook)|\\.sh|_lazy_load_${tool}|_dot_lazy[[:space:]]+${tool})" \
+    "$HOME/.config/zsh" "$HOME/.config/fish" "$HOME/.config/shell" 2>/dev/null; then
+    init_referenced=1
+  fi
+  ((init_referenced == 0)) && continue
+  # Tools we lazy-load via shell stubs don't need init-eval cache files.
+  case "$tool" in
+    fnm | nvm | sdkman)
+      grep -rIlqE "_lazy_load_${tool}|_dot_lazy[[:space:]]+${tool}" \
+        "$HOME/.config/zsh" "$HOME/.config/fish" 2>/dev/null && continue
+      ;;
+  esac
   found=0
   for shell_dir in zsh bash fish; do
     case "$shell_dir" in
@@ -585,27 +606,36 @@ if command -v zsh >/dev/null 2>&1; then
   fi
 fi
 
-# 4. PATH length. Each entry is searched on every command resolution;
-# >40 entries is noticeably slow on cold-cache filesystems.
+# 4. PATH length. Each entry is searched on every command resolution.
+# A mise-managed 2026 dev machine routinely adds 60-90 entries (one per
+# installed tool version + per-shim path), so the warn/fail thresholds
+# reflect that baseline rather than a lean default (~40).
 path_count=$(printf '%s' "${PATH:-}" | tr ':' '\n' | grep -c . || true)
-if [[ "$path_count" -le 40 ]]; then
+if [[ "$path_count" -le 75 ]]; then
   _ok "PATH length" "$path_count entries"
-elif [[ "$path_count" -le 80 ]]; then
+elif [[ "$path_count" -le 120 ]]; then
   _warn "PATH length" "$path_count entries — consider pruning"
 else
   _fail "PATH length" "$path_count entries — likely slowing every command"
 fi
 
 # 5. Shell coverage. Surface installed shells that the project's caching
-# infrastructure (zsh/bash/fish) doesn't currently maintain caches for.
+# infrastructure doesn't currently maintain caches for. zsh/bash/fish/nu
+# all have a `_cached_eval` analogue; pwsh does not.
 shells_unmanaged=""
 for sh in nu pwsh; do
-  command -v "$sh" >/dev/null 2>&1 && shells_unmanaged="${shells_unmanaged:+$shells_unmanaged, }$sh"
+  command -v "$sh" >/dev/null 2>&1 || continue
+  case "$sh" in
+    nu)
+      [[ -f "$HOME/.config/nushell/cached_eval.nu" ]] && continue
+      ;;
+  esac
+  shells_unmanaged="${shells_unmanaged:+$shells_unmanaged, }$sh"
 done
 if [[ -z "$shells_unmanaged" ]]; then
-  _ok "shell coverage" "all installed shells (zsh/bash/fish) are managed"
+  _ok "shell coverage" "all installed shells have _cached_eval support"
 else
-  _warn "shell coverage" "$shells_unmanaged installed — startup not measured by dot perf"
+  _warn "shell coverage" "$shells_unmanaged installed — no _cached_eval helper"
 fi
 
 # 6. Zsh hook count. Heavy precmd/preexec functions compound per-prompt.

package/scripts/diagnostics/drift-dashboard.sh

@@ -30,9 +30,9 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-# shellcheck source=../dot/lib/ui.sh
+# shellcheck source=../../lib/dot/ui.sh
 # shellcheck disable=SC1091
-source "$SCRIPT_DIR/../dot/lib/ui.sh"
+source "$SCRIPT_DIR/../../lib/dot/ui.sh"
 
 JSON_MODE=0
 SHOW_DIFF="${DOTFILES_DRIFT_SHOW_DIFF:-0}"

package/scripts/diagnostics/health.sh

@@ -6,12 +6,12 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-# shellcheck source=../dot/lib/ui.sh
+# shellcheck source=../../lib/dot/ui.sh
 # shellcheck disable=SC1091
-source "$SCRIPT_DIR/../dot/lib/ui.sh"
-# shellcheck source=../dot/lib/log.sh
+source "$SCRIPT_DIR/../../lib/dot/ui.sh"
+# shellcheck source=../../lib/dot/log.sh
 # shellcheck disable=SC1091
-source "$SCRIPT_DIR/../dot/lib/log.sh"
+source "$SCRIPT_DIR/../../lib/dot/log.sh"
 
 # Portable has_command (self-contained; no dependency on utils.sh)
 has_command() { command -v "$1" >/dev/null 2>&1; }

package/scripts/diagnostics/history-analysis.sh

@@ -3,9 +3,9 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-# shellcheck source=../dot/lib/ui.sh
+# shellcheck source=../../lib/dot/ui.sh
 # shellcheck disable=SC1091
-source "$SCRIPT_DIR/../dot/lib/ui.sh"
+source "$SCRIPT_DIR/../../lib/dot/ui.sh"
 
 histfile="${HISTFILE:-$HOME/.zsh_history}"
 db="${DOTFILES_HISTORY_DB:-$HOME/.local/share/dotfiles/history.sqlite}"