@sebastienrousseau/dotfiles 0.2.510 → 0.2.512

package/scripts/ops/chezmoi-apply.sh

@@ -199,6 +199,7 @@ _AI_PROVIDERS=(
   "copilot|npm:@github/copilot|Copilot CLI"
   "goose|native|Goose"
   "agy|native|Antigravity CLI"
+  "kimi|native|Kimi CLI"
   "sgpt|pipx:shell-gpt|Shell-GPT"
   "ollama|aqua:ollama/ollama|Ollama"
   "opencode|npm:opencode-ai|OpenCode"
@@ -276,6 +277,10 @@ if [[ ${#_ai_missing[@]} -gt 0 ]] && [[ "$INTERACTIVE" == "1" ]]; then
           install_agy_native "$_label"
           continue
         fi
+        if [[ "$_bin" == "kimi" ]]; then
+          install_kimi_native "$_label"
+          continue
+        fi
         if command -v gum &>/dev/null; then
           if gum spin --spinner dot --title "Installing $_label ($_pkg)" -- \
             mise use -g "$_pkg@latest" 2>&1; then

package/scripts/ops/release.sh

@@ -19,6 +19,8 @@ source "$SCRIPT_DIR/../../lib/dot/ui.sh"
 source "$SCRIPT_DIR/../../lib/dot/log.sh"
 export DOT_COMMAND="release"
 ui_init
+BOLD="${BOLD:-}"
+NC="${NC:-}"
 
 log_info() { ui_info "$@"; }
 log_success() { ui_ok "$@"; }
@@ -129,11 +131,18 @@ main() {
   done
 
   # Concurrency guard
-  LOCK_FILE="${XDG_RUNTIME_DIR:-/tmp}/dotfiles-release.lock"
-  exec 9>"$LOCK_FILE"
-  if ! flock -n 9; then
-    ui_warn "Already running" "Another release is in progress"
-    exit 0
+  local lock_dir
+  lock_dir="${XDG_RUNTIME_DIR:-${TMPDIR:-/tmp}}"
+  if [[ ! -d "$lock_dir" || ! -w "$lock_dir" ]]; then
+    lock_dir="${TMPDIR:-/tmp}"
+  fi
+  LOCK_FILE="$lock_dir/dotfiles-release.lock"
+  if command -v flock >/dev/null 2>&1; then
+    exec 9>"$LOCK_FILE"
+    if ! flock -n 9; then
+      ui_warn "Already running" "Another release is in progress"
+      exit 0
+    fi
   fi
 
   cd "$PROJECT_ROOT"

package/scripts/qa/docs-coverage.sh

@@ -54,7 +54,7 @@ check_dot_command_docs() {
 check_ai_provider_docs() {
   local provider=""
 
-  for provider in cl copilot agy kiro sgpt ollama opencode aider; do
+  for provider in cl copilot kimi agy kiro sgpt ollama opencode aider; do
     record_doc_check "dot $provider in AI.md" "\`dot $provider\`" "$AI_DOC"
   done
 }

package/scripts/qa/reliability-audit.sh

@@ -65,12 +65,12 @@ shell_syntax() {
 
 unit_tests() {
   cd "$REPO_ROOT"
-  ./tests/framework/test_runner.sh
+  ./tests/framework/test_runner.sh --jobs auto
 }
 
 integration_tests() {
   cd "$REPO_ROOT"
-  RUN_INTEGRATION=1 ./tests/framework/test_runner.sh -i
+  RUN_INTEGRATION=1 ./tests/framework/test_runner.sh --jobs auto -i
 }
 
 coverage_gate() {

package/scripts/secrets/age-init.sh

@@ -39,7 +39,8 @@ if config_path.exists():
 
 lines = content.splitlines()
 
-# Remove existing encryption/age block
+# Remove existing encryption keys and age blocks regardless of where a previous
+# run placed them.
 out = []
 in_age = False
 for line in lines:
@@ -57,9 +58,19 @@ for line in lines:
             continue
         out.append(line)
 
-# Append updated config (use json.dumps for safe string escaping)
-out.append("")
-out.append("encryption = \"age\"")
+# Keep encryption at top level; chezmoi warns when it is nested under [data].
+insert_at = 0
+for i, line in enumerate(out):
+    if line.strip().startswith("["):
+        insert_at = i
+        break
+else:
+    insert_at = len(out)
+
+top_level = ["encryption = \"age\"", ""]
+out[insert_at:insert_at] = top_level
+
+# Append updated age config (use json.dumps for safe string escaping)
 out.append("")
 out.append("[age]")
 out.append(f"identity = {json.dumps(key_file)}")

package/scripts/theme/apply-gnome-theme.sh

@@ -56,7 +56,7 @@ success() {
 }
 
 # Check if we're running GNOME
-if [ "$XDG_CURRENT_DESKTOP" != "GNOME" ] && [ "$XDG_SESSION_DESKTOP" != "gnome" ]; then
+if [ "${XDG_CURRENT_DESKTOP:-}" != "GNOME" ] && [ "${XDG_SESSION_DESKTOP:-}" != "gnome" ]; then
   warn "Not running GNOME desktop. Some settings may not apply."
 fi
 
@@ -208,7 +208,11 @@ apply_wallpaper() {
   # Pick a random wallpaper matching the mode from curated collection
   local wp=""
   if [ -d "$wallpaper_dir" ]; then
-    wp="$(find "$wallpaper_dir" -maxdepth 1 -type f -iname "*-${mode}.jpg" 2>/dev/null | shuf -n 1 || true)"
+    if command -v shuf >/dev/null 2>&1; then
+      wp="$(find "$wallpaper_dir" -maxdepth 1 -type f -iname "*-${mode}.jpg" 2>/dev/null | shuf -n 1 || true)"
+    else
+      wp="$(find "$wallpaper_dir" -maxdepth 1 -type f -iname "*-${mode}.jpg" 2>/dev/null | sort | head -n 1 || true)"
+    fi
   fi
 
   # Fallback: check Catppuccin system/user wallpapers

package/scripts/theme/extract-theme.py

@@ -339,42 +339,77 @@ def _nvim_from_hue(hue: float, is_dark: bool) -> Tuple[str, str]:
 
 
 def _macos_accent_from_hue(hue: float) -> int:
-    """Map accent hue angle to macOS accent color integer."""
-    if hue < 30 or hue >= 345:
+    """Map a CIELAB hue angle to a macOS accent-colour integer.
+
+    Boundaries are calibrated to the CIELAB hues of Apple's own accent
+    swatches (not HSL): red≈36°, orange≈67°, yellow≈87°, green≈144°,
+    blue≈287°, purple≈317°. The previous HSL-style cutoffs pushed blue
+    accents (~283°) into Purple and purple into Pink.
+    """
+    hue = hue % 360
+    if hue < 15 or hue >= 345:
+        return 6   # Pink / magenta
+    if hue < 50:
         return 0   # Red
-    if hue < 60:
+    if hue < 77:
         return 1   # Orange
-    if hue < 105:
+    if hue < 110:
         return 2   # Yellow
-    if hue < 165:
+    if hue < 200:
         return 3   # Green
-    if hue < 255:
-        return 4   # Blue
     if hue < 300:
-        return 5   # Purple
-    return 6       # Pink
+        return 4   # Blue (incl. teal-blue and navy)
+    return 5       # Purple / indigo (300–345)
+
+
+def _env_hex(key: str, fallback: str) -> str:
+    """A #rrggbb value from env, or the fallback when unset/invalid."""
+    v = os.environ.get(key, "")
+    if len(v) == 7 and v[0] == "#":
+        try:
+            hex_to_rgb(v)
+            return v
+        except ValueError:
+            pass
+    return fallback
 
 
 def _compute_bg_fg(clusters, is_dark):
-    """Select background and foreground from clustered colors."""
-    sorted_by_L = sorted(clusters, key=lambda c: c[0][0])
+    """Terminal background/foreground — fixed, engineered neutrals per mode.
+
+    Deliberately NOT derived from the wallpaper: a terminal wants a
+    high-contrast, low-eye-strain surface that stays stable across themes.
+    Dark mode uses a deep neutral grey with off-white text; light mode a warm
+    paper cream with charcoal text. The wallpaper still drives the accent and
+    the 16 ANSI colours (which are computed against this bg for contrast).
+    Override per mode via DOTFILES_TERM_BG_DARK / _FG_DARK / _BG_LIGHT /
+    _FG_LIGHT.
+    """
+    _ = clusters  # bg/fg no longer wallpaper-derived
     if is_dark:
-        bg_lab = sorted_by_L[0][0]
-        bg_lab = (min(bg_lab[0], 15.0), bg_lab[1] * 0.3, bg_lab[2] * 0.3)
-        fg_lab = (88.0, bg_lab[1] * 0.1, bg_lab[2] * 0.1)
+        bg_rgb = hex_to_rgb(_env_hex("DOTFILES_TERM_BG_DARK", "#1e1e2e"))
+        fg_rgb = hex_to_rgb(_env_hex("DOTFILES_TERM_FG_DARK", "#d4d4d4"))
     else:
-        bg_lab = sorted_by_L[-1][0]
-        bg_lab = (max(bg_lab[0], 92.0), bg_lab[1] * 0.15, bg_lab[2] * 0.15)
-        fg_lab = (18.0, bg_lab[1] * 0.15, bg_lab[2] * 0.15)
-    bg_rgb = lab_to_rgb(*bg_lab)
-    fg_rgb = ensure_contrast(lab_to_rgb(*fg_lab), bg_rgb, 7.0, is_dark)
+        bg_rgb = hex_to_rgb(_env_hex("DOTFILES_TERM_BG_LIGHT", "#fbf1c7"))
+        fg_rgb = hex_to_rgb(_env_hex("DOTFILES_TERM_FG_LIGHT", "#3c3836"))
+    bg_lab = rgb_to_lab(*bg_rgb)
     return bg_lab, bg_rgb, fg_rgb
 
 
 def _compute_accent(clusters, is_dark):
-    """Select and AAA-compliant-darken the most saturated cluster for accent."""
-    sorted_by_chroma = sorted(clusters, key=lambda c: lab_chroma(*c[0]), reverse=True)
-    accent_lab = sorted_by_chroma[0][0]
+    """Select the accent from the wallpaper's DOMINANT chromatic colour.
+
+    Rank clusters by population x chroma so the accent follows the *main*
+    colour of the wallpaper (a large, colourful region) rather than the
+    single most-saturated cluster — which is often a tiny vivid splash
+    that doesn't represent the image. Near-neutral clusters score ~0 and
+    are skipped; if the whole image is neutral we fall back to the most
+    saturated cluster so the accent still carries a hue. The selected
+    colour is then AAA-darkened below (ADR-009 contrast requirement)."""
+    ranked = sorted(clusters, key=lambda c: c[1] * lab_chroma(*c[0]), reverse=True)
+    accent_lab = ranked[0][0]
+    if lab_chroma(*accent_lab) < 5.0:
+        accent_lab = max(clusters, key=lambda c: lab_chroma(*c[0]))[0]
     if is_dark:
         accent_lab = (max(accent_lab[0], 35.0), accent_lab[1], accent_lab[2])
     else:
@@ -412,16 +447,30 @@ def _compute_panel_border(bg_lab, bg_rgb, is_dark):
 
 def _build_ansi_color(base_lab, accent_lab, bg_rgb, is_dark):
     """Build normal + bright ANSI variant from a base Lab color."""
+    normal_L = (
+        max(55.0, min(75.0, base_lab[0])) if is_dark
+        else max(30.0, min(50.0, base_lab[0]))
+    )
+    normal = adjust_lightness(base_lab, normal_L)
     if is_dark:
-        normal_L = max(55.0, min(75.0, base_lab[0]))
-        bright_L = normal_L + 12
+        # Dark bg: the bright variant pops by getting lighter.
+        bright = adjust_lightness(base_lab, normal_L + 12)
+        bright_min = 4.5
     else:
-        normal_L = max(30.0, min(50.0, base_lab[0]))
-        bright_L = normal_L - 8
-    normal = adjust_lightness(base_lab, normal_L)
-    bright = adjust_lightness(base_lab, bright_L)
-    normal_rgb = ensure_contrast(lab_to_rgb(*normal), bg_rgb, 3.0, is_dark)
-    bright_rgb = ensure_contrast(lab_to_rgb(*bright), bg_rgb, 4.5, is_dark)
+        # Light bg: a lighter bright would wash out against near-white, so
+        # brighten by vividness at equal lightness instead — the bright is
+        # never darker than the normal (matches Apple's light ANSI ramp,
+        # where brights read as more saturated, not muddier).
+        bright = (normal[0], normal[1] * 1.25, normal[2] * 1.25)
+        bright_min = 7.0
+    # WCAG AAA (7:1) for the chromatic slots on a light bg so coloured text
+    # (paths, syntax) is unambiguously legible — AA (4.5:1) still read as washed
+    # out on cream. Brights stay AAA too and differ from normals by saturation
+    # (Apple's light ramp), not lightness. Dark mode keeps its lower floor
+    # (light text on dark reads comfortably at a lower ratio).
+    normal_min = 3.0 if is_dark else 7.0
+    normal_rgb = ensure_contrast(lab_to_rgb(*normal), bg_rgb, normal_min, is_dark)
+    bright_rgb = ensure_contrast(lab_to_rgb(*bright), bg_rgb, bright_min, is_dark)
     return normal_rgb, bright_rgb
 
 
@@ -455,11 +504,18 @@ def _structural_colors(bg_lab, bg_rgb, is_dark):
             ensure_contrast(lab_to_rgb(bg_lab[0] + 25, bg_lab[1], bg_lab[2]), bg_rgb, 2.5, True),
             ensure_contrast(lab_to_rgb(90.0, bg_lab[1] * 0.05, bg_lab[2] * 0.05), bg_rgb, 7.0, True),
         )
+    # Light bg: the neutral ramp increases in lightness (c0 < c8 < c7 < c15).
+    # c0/c8/c7 stay readable (>= AA); c15 ("bright white") is the LIGHTEST tone,
+    # strictly lighter than c7 — bright-white text legibility is gated by fg, not
+    # c15, and forcing c15 to the same floor as c7 made them converge (c15 ended
+    # a hair darker, breaking the ramp). Start c15 well above c7 with only a mild
+    # floor so it stays the lightest. (Terminals render the dark palette; this
+    # ramp only feeds non-terminal light-palette consumers.)
     return (
         ensure_contrast(lab_to_rgb(18.0, bg_lab[1] * 0.2, bg_lab[2] * 0.2), bg_rgb, 7.0, False),
-        ensure_contrast(lab_to_rgb(bg_lab[0] - 8, bg_lab[1], bg_lab[2]), bg_rgb, 1.3, False),
+        ensure_contrast(lab_to_rgb(50.0, bg_lab[1] * 0.15, bg_lab[2] * 0.15), bg_rgb, 4.5, False),
         ensure_contrast(lab_to_rgb(35.0, bg_lab[1] * 0.2, bg_lab[2] * 0.2), bg_rgb, 4.5, False),
-        ensure_contrast(lab_to_rgb(8.0, 0, 0), bg_rgb, 10.0, False),
+        ensure_contrast(lab_to_rgb(64.0, bg_lab[1] * 0.08, bg_lab[2] * 0.08), bg_rgb, 2.5, False),
     )
 
 
@@ -664,7 +720,15 @@ def main():
     # Generate theme
     theme = generate_theme(clusters, name, is_dark)
     wp_base = args.image.split("[")[0] if "[" in args.image else args.image
-    theme["wallpaper"] = os.path.abspath(wp_base)
+    wp_abs = os.path.abspath(wp_base)
+    # Store home-relative with a `~` so the committed themes.toml is not tied to
+    # one machine's username. Consumers (wallpaper-sync.sh) expand `~/`. System
+    # wallpapers (/System/..., /usr/share/...) stay absolute — identical on
+    # every host anyway.
+    home = os.path.expanduser("~")
+    if wp_abs == home or wp_abs.startswith(home + os.sep):
+        wp_abs = "~" + wp_abs[len(home):]
+    theme["wallpaper"] = wp_abs
     theme["source"] = args.source
 
     # Output

package/scripts/theme/rebuild-themes.sh

@@ -124,51 +124,99 @@ discover_linux_system() {
     /usr/share/wallpapers
   )
 
-  local dir file name
+  local dir file name variant
   for dir in "${dirs[@]}"; do
     [[ -d "$dir" ]] || continue
     while IFS= read -r file; do
       name="$(basename "$file")"
       name="${name%.*}"
-      name="$(echo "$name" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')"
+      name="$(echo "$name" | tr '[:upper:]' '[:lower:]' | tr ' _' '--')"
       name="${name//[^a-z0-9-]/}"
-      # Avoid duplicates — first found wins for system
-      if [[ -z "${WALLPAPERS[$name]+x}" ]]; then
-        WALLPAPERS["$name"]="$file"
-        WP_SOURCE["$name"]="system"
+      while [[ "$name" == *--* ]]; do name="${name//--/-}"; done
+      name="${name#-}"
+      name="${name%-}"
+      [[ -n "$name" ]] || continue
+      # Static system images carry no mode; theme them in both modes so
+      # they show as a pair (unless the file is already a -dark/-light).
+      if [[ "$name" == *-dark || "$name" == *-light ]]; then
+        [[ -z "${WALLPAPERS[$name]+x}" ]] && {
+          WALLPAPERS["$name"]="$file"
+          WP_SOURCE["$name"]="system"
+        }
+        continue
       fi
-    done < <(find "$dir" -maxdepth 3 -type f \( -name "*.jpg" -o -name "*.png" -o -name "*.heic" \) 2>/dev/null | sort)
+      local key
+      for variant in dark light; do
+        key="${name}-${variant}"
+        if [[ -z "${WALLPAPERS[$key]+x}" ]]; then
+          WALLPAPERS["$key"]="$file"
+          WP_SOURCE["$key"]="system"
+        fi
+      done
+    done < <(find "$dir" -maxdepth 3 -type f \
+      \( -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.png' \
+      -o -iname '*.heic' -o -iname '*.webp' -o -iname '*.tiff' \) 2>/dev/null | sort)
   done
 }
 
 discover_custom() {
   [[ -d "$CUSTOM_DIR" ]] || return 0
 
-  local file name frame_count
-  for file in "$CUSTOM_DIR"/*.heic "$CUSTOM_DIR"/*.jpg "$CUSTOM_DIR"/*.png; do
+  local file base name ext frame_count
+  # Case-insensitive, wide extension match. The old fixed-glob loop
+  # (`*.heic *.jpg *.png`) silently dropped `.jpeg`, `.webp`, `.tiff`
+  # and every uppercase variant (`.JPG`, `.HEIC`, …), so those
+  # wallpapers never made it into the theme table.
+  while IFS= read -r file; do
     [[ -f "$file" ]] || continue
-    name="$(basename "$file")"
-    name="${name%.*}"
+    base="$(basename "$file")"
+    base="${base%.*}"
+    ext="$(echo "${file##*.}" | tr '[:upper:]' '[:lower:]')"
+
+    # Normalize to the [a-z0-9-] namespace that themes.toml and the
+    # `dot theme list` picker regex both require — a raw name with
+    # spaces/uppercase would generate a section the picker can't match.
+    name="$(echo "$base" | tr '[:upper:]' '[:lower:]' | tr ' _' '--')"
+    name="${name//[^a-z0-9-]/}"
+    while [[ "$name" == *--* ]]; do name="${name//--/-}"; done
+    name="${name#-}"
+    name="${name%-}"
+    [[ -n "$name" ]] || continue
 
-    # Check if this is a dynamic HEIC (multi-frame = light+dark in one file)
-    if [[ "${file##*.}" == "heic" ]]; then
+    # Dynamic HEIC (multi-frame = light+dark packed in one file).
+    if [[ "$ext" == "heic" ]]; then
       frame_count="$(magick identify "$file" 2>/dev/null | wc -l | tr -d ' ')"
       if [[ "$frame_count" -ge 2 && "$name" != *-dark && "$name" != *-light ]]; then
-        # Dynamic HEIC: register as both dark and light
         WALLPAPERS["${name}-light"]="${file}[0]"
         WP_SOURCE["${name}-light"]="custom"
         WALLPAPERS["${name}-dark"]="${file}[1]"
         WP_SOURCE["${name}-dark"]="custom"
-        # Store the original file path for wallpaper-sync
+        # Store the original file path for wallpaper-sync.
         WALLPAPERS["${name}"]="$file"
         WP_SOURCE["${name}"]="custom-dynamic"
         continue
       fi
     fi
 
-    WALLPAPERS["$name"]="$file"
-    WP_SOURCE["$name"]="custom"
-  done
+    # Explicitly-named single-mode variant (foo-dark.jpg / foo-light.jpg):
+    # honour the author's mode, register the one variant as-is.
+    if [[ "$name" == *-dark || "$name" == *-light ]]; then
+      WALLPAPERS["$name"]="$file"
+      WP_SOURCE["$name"]="custom"
+      continue
+    fi
+
+    # Static single image: theme it in BOTH modes (extract-theme forces
+    # the mode from the -dark/-light suffix) so it appears as a light/dark
+    # pair in `dot theme list`. Previously a static produced only one
+    # variant and paired_families() hid it entirely.
+    WALLPAPERS["${name}-dark"]="$file"
+    WP_SOURCE["${name}-dark"]="custom"
+    WALLPAPERS["${name}-light"]="$file"
+    WP_SOURCE["${name}-light"]="custom"
+  done < <(find "$CUSTOM_DIR" -maxdepth 1 -type f \
+    \( -iname '*.heic' -o -iname '*.jpg' -o -iname '*.jpeg' \
+    -o -iname '*.png' -o -iname '*.webp' -o -iname '*.tiff' \) 2>/dev/null | sort)
 }
 
 # Remove dynamic base entries (keep only the -dark/-light variants for theme gen)
@@ -181,11 +229,15 @@ cleanup_dynamic_entries() {
   done
 }
 
-# Discover in order: system first, custom overrides
-case "$(uname -s)" in
-  Darwin) discover_macos_system ;;
-  Linux) discover_linux_system ;;
-esac
+# Discover in order: system first, custom overrides. System (OS-shipped)
+# wallpapers are opt-in — most users only want themes from their own
+# wallpapers. Enable the ~100 built-in ones with DOTFILES_THEME_SYSTEM=1.
+if [[ "${DOTFILES_THEME_SYSTEM:-0}" == "1" ]]; then
+  case "$(uname -s)" in
+    Darwin) discover_macos_system ;;
+    Linux) discover_linux_system ;;
+  esac
+fi
 discover_custom
 cleanup_dynamic_entries
 
@@ -238,16 +290,29 @@ done
 # Generate themes
 # ---------------------------------------------------------------------------
 
-sys_count=0
-cust_count=0
+# Report distinct WALLPAPERS (families), not theme sections. Every
+# wallpaper — a dynamic HEIC (light+dark frames) or a static image —
+# yields a `-light` and a `-dark` theme, so a raw section count is ~2x
+# the file count and reads as wrong ("74 files → 148 custom"). Collapse
+# -dark/-light back to the family so the numbers match what's on disk
+# and what `dot theme list` shows, and report the theme total separately.
+# Explicit empty init: a `declare -A x` that never gets a key still trips
+# `set -u` on ${#x[@]} (even in bash 5) — happens now that system wallpapers
+# are opt-in and sys_fam can stay empty.
+declare -A sys_fam=() cust_fam=()
 for name in "${!WP_SOURCE[@]}"; do
+  family="${name%-dark}"
+  family="${family%-light}"
   case "${WP_SOURCE[$name]}" in
-    system) sys_count=$((sys_count + 1)) ;;
-    custom) cust_count=$((cust_count + 1)) ;;
+    system) sys_fam["$family"]=1 ;;
+    custom) cust_fam["$family"]=1 ;;
   esac
 done
+sys_count=${#sys_fam[@]}
+cust_count=${#cust_fam[@]}
 echo "Discovering wallpapers..."
-echo "  Found: $sys_count system, $cust_count custom (${#WALLPAPERS[@]} total)"
+echo "  Found: $sys_count system, $cust_count custom wallpapers" \
+  "($((sys_count + cust_count)) total → ${#WALLPAPERS[@]} light/dark themes)"
 echo ""
 
 GENERATED=0
@@ -297,11 +362,20 @@ if [[ $TOTAL_WORK -gt 0 ]]; then
   wait
 fi
 
-# Count results
-GENERATED=$(find "$CACHE_DIR" -name "*.toml" -newer "$0" 2>/dev/null | wc -l | tr -d ' ')
-FAILED=$((TOTAL_WORK - GENERATED))
+# Count results — how many of THIS run's work items produced a cache file.
+# (The old `find -newer "$0"` counted every cache file newer than the script,
+# so when everything was cached FAILED went negative.)
+GENERATED=0
+FAILED=0
+for name in "${WORK[@]}"; do
+  if [[ -f "$CACHE_DIR/${name}.toml" ]]; then
+    GENERATED=$((GENERATED + 1))
+  else
+    FAILED=$((FAILED + 1))
+  fi
+done
 echo ""
-echo "Results: $TOTAL_WORK processed, $CACHED cached, $FAILED failed"
+echo "Results: $GENERATED generated, $CACHED cached, $FAILED failed"
 
 # ---------------------------------------------------------------------------
 # Assemble themes.toml
@@ -326,14 +400,145 @@ echo "Assembling themes.toml..."
 
 HEADER
 
-  for cache_file in "$CACHE_DIR"/*.toml; do
+  # Assemble ONLY the wallpapers discovered this run, not every file left in
+  # the cache. This drops themes for wallpapers no longer present (e.g. system
+  # wallpapers once DOTFILES_THEME_SYSTEM is turned off) instead of letting
+  # stale cache entries pile up in themes.toml.
+  for name in $(printf '%s\n' "${!WALLPAPERS[@]}" | sort); do
+    cache_file="$CACHE_DIR/${name}.toml"
     [[ -f "$cache_file" ]] || continue
     echo ""
     cat "$cache_file"
   done
+
+  # Synthetic fallback themes — always emitted, never wallpaper-derived.
+  # Every theme template degrades to `fallback-dark` when `.theme` is unset or
+  # names a theme absent from this file. Because these are re-emitted on every
+  # rebuild, a regeneration that drops any wallpaper theme can never break the
+  # fallback (unlike hardcoding a wallpaper theme like the old big-sur-dark).
+  # switch.sh hides the `fallback` family from user-facing theme lists.
+  cat <<'FALLBACK'
+
+# ─────────────────────────────────────────────────────────────────────
+# Synthetic fallback themes (NOT wallpaper-derived, NEVER user-selectable).
+# ─────────────────────────────────────────────────────────────────────
+
+[themes.fallback-dark]
+mode = "dark"
+family = "fallback"
+macos_accent = 4
+wallpaper = ""
+source = "custom"
+
+[themes.fallback-dark.term]
+bg = "#1e1e2e"
+fg = "#d4d4d4"
+cursor = "#455c67"
+cursor_text = "#1e1e2e"
+sel_bg = "#394145"
+sel_fg = "#d4d4d4"
+c0  = "#3c3c4d"
+c1  = "#997d7a"
+c2  = "#479174"
+c3  = "#8a836f"
+c4  = "#5f86b7"
+c5  = "#917e8e"
+c6  = "#5c8d82"
+c7  = "#b9b8bb"
+c8  = "#605f72"
+c9  = "#bf9b97"
+c10 = "#67b293"
+c11 = "#aba389"
+c12 = "#7fa6d9"
+c13 = "#b49cb0"
+c14 = "#7bada1"
+c15 = "#e2e2e3"
+
+[themes.fallback-dark.ui]
+accent = "#455c67"
+accent_text = "#ffffff"
+error = "#997d7a"
+warning = "#8a836f"
+success = "#479174"
+info = "#5f86b7"
+panel = "#242435"
+border = "#302f38"
+
+[themes.fallback-dark.app]
+nvim = "tokyonight"
+nvim_style = "night"
+lualine = "tokyonight"
+gtk_theme = "Adwaita-dark"
+gtk_icon = "Papirus-Dark"
+gnome_shell = ""
+gnome_gtk = "Adwaita-dark"
+vscode = "Tokyonight Mocha"
+vscode_dark = "Tokyonight Mocha"
+vscode_light = "Tokyonight Latte"
+cat_wallpaper = ""
+starship_palette = "catppuccin_mocha"
+
+
+[themes.fallback-light]
+mode = "light"
+family = "fallback"
+macos_accent = 4
+wallpaper = ""
+source = "custom"
+
+[themes.fallback-light.term]
+bg = "#fbf1c7"
+fg = "#3c3836"
+cursor = "#2c5989"
+cursor_text = "#fbf1c7"
+sel_bg = "#c6cfe0"
+sel_fg = "#3c3836"
+c0  = "#2e2c26"
+c1  = "#7d3d39"
+c2  = "#205a48"
+c3  = "#5b501d"
+c4  = "#2b527d"
+c5  = "#6e4069"
+c6  = "#25554c"
+c7  = "#6f6d67"
+c8  = "#54524b"
+c9  = "#853733"
+c10 = "#025c46"
+c11 = "#5b500b"
+c12 = "#0d5388"
+c13 = "#743b6f"
+c14 = "#15564b"
+c15 = "#979693"
+
+[themes.fallback-light.ui]
+accent = "#2c5989"
+accent_text = "#ffffff"
+error = "#7d3d39"
+warning = "#5b501d"
+success = "#205a48"
+info = "#2b527d"
+panel = "#f2e8bf"
+border = "#e3e0d3"
+
+[themes.fallback-light.app]
+nvim = "catppuccin"
+nvim_style = "latte"
+lualine = "catppuccin"
+gtk_theme = "Adwaita"
+gtk_icon = "Papirus-Light"
+gnome_shell = ""
+gnome_gtk = "Adwaita"
+vscode = "Catppuccin Latte"
+vscode_dark = "Catppuccin Mocha"
+vscode_light = "Catppuccin Latte"
+cat_wallpaper = ""
+starship_palette = "catppuccin_latte"
+FALLBACK
 } >"$THEMES_FILE"
 
-theme_count=$(grep -c '^\[themes\.' "$THEMES_FILE" | head -1)
-echo "  Written: $THEMES_FILE ($theme_count theme sections)"
+# Count top-level [themes.NAME] blocks only — not the .term/.ui/.app
+# subsections (which inflated the tally ~4x).
+theme_count=$(grep -cE '^\[themes\.[a-z0-9-]+\]$' "$THEMES_FILE")
+echo "  Written: $THEMES_FILE ($theme_count themes)"
 echo ""
 echo "Done. Run 'dot theme list' to see available themes."