@sebastienrousseau/dotfiles 0.2.511 → 0.2.513

package/scripts/ops/bundle.sh

@@ -15,12 +15,38 @@ source "$SCRIPT_DIR/../lib/dot/ui.sh"
 source "$SCRIPT_DIR/../lib/dot/log.sh"
 export DOT_COMMAND="bundle"
 
+usage() {
+  cat <<'EOF'
+Usage: bundle.sh [output-dir]
+
+Create an offline dotfiles bundle as a .tar.zst archive.
+EOF
+}
+
+case "${1:-}" in
+  --help | -h)
+    usage
+    exit 0
+    ;;
+  -*)
+    printf 'Unknown option: %s\n' "$1" >&2
+    usage >&2
+    exit 2
+    ;;
+esac
+
 # Concurrency guard
-LOCK_FILE="${XDG_RUNTIME_DIR:-/tmp}/dotfiles-bundle.lock"
-exec 9>"$LOCK_FILE"
-if ! flock -n 9; then
-  ui_warn "Already running" "Another bundle instance is active"
-  exit 0
+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-bundle.lock"
+if command -v flock >/dev/null 2>&1; then
+  exec 9>"$LOCK_FILE"
+  if ! flock -n 9; then
+    ui_warn "Already running" "Another bundle instance is active"
+    exit 0
+  fi
 fi
 
 OUTPUT_DIR="${1:-$HOME/Downloads}"

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/heal-tools.sh

@@ -3,6 +3,10 @@
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # shellcheck disable=SC2034
 # =============================================================================
+
+HEAL_TOOLS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../../lib/dot/verified-download.sh disable=SC1091
+source "$HEAL_TOOLS_DIR/../../lib/dot/verified-download.sh"
 # heal-tools.sh — Tool installation helpers for heal.sh
 # Sourced by heal.sh; inherits set -euo pipefail, ui.sh, and shared variables.
 # =============================================================================
@@ -123,33 +127,56 @@ get_package_name() {
 # Usage: _pkg_install "label" completed total command [args...]
 _pkg_install() { ui_run_cmd "$@"; }
 
-# Resolve latest GitHub release tag for a repo
-_gh_latest_tag() {
-  curl -fsSLI -o /dev/null -w '%{url_effective}' "https://github.com/$1/releases/latest" | sed 's|.*/||'
+_mise_tool_specs() {
+  case "$1" in
+    nushell) printf '%s\n' 'aqua:nushell/nushell@0.114.1' ;;
+    pueue)
+      printf '%s\n' 'aqua:Nukesor/pueue/pueue@4.0.4'
+      printf '%s\n' 'aqua:Nukesor/pueue/pueued@4.0.4'
+      ;;
+    wasmtime) printf '%s\n' 'wasmtime@47.0.3' ;;
+    sops) printf '%s\n' 'sops@3.13.3' ;;
+    yazi) printf '%s\n' 'yazi@26.5.6' ;;
+    zellij) printf '%s\n' 'zellij@0.44.3' ;;
+    *) return 1 ;;
+  esac
+}
+
+_install_with_mise() {
+  local cmd="$1" spec
+  command -v mise >/dev/null 2>&1 || return 1
+  while IFS= read -r spec; do
+    [[ -n "$spec" ]] || continue
+    # --pin writes an exact version to the user's writable global config;
+    # aqua/ubi backends verify publisher-provided checksums before install.
+    mise use --global --pin "$spec" || return 1
+  done < <(_mise_tool_specs "$cmd")
 }
 
 # Install a single package (dispatcher for _pkg_install to call in subshell)
 _do_install() {
   local cmd="$1"
   local pkg_mgr="$2"
-  local bin_dir="$HOME/.local/bin"
-  mkdir -p "$bin_dir"
+
+  case "$cmd" in
+    nushell | pueue | wasmtime | sops | yazi | zellij)
+      if _install_with_mise "$cmd"; then
+        return 0
+      fi
+      log_warn "mise install unavailable for $cmd; trying $pkg_mgr"
+      ;;
+  esac
 
   # Binary/curl installers for tools not in standard apt repos
   case "$cmd" in
     starship)
       local installer
       installer=$(umask 077 && mktemp)
-      if ! curl -fsSL -o "$installer" https://starship.rs/install.sh; then
+      if ! download_verified_script https://starship.rs/install.sh "$installer"; then
         rm -f "$installer"
         log_error "Failed to download starship installer"
         return 1
       fi
-      if ! head -1 "$installer" | grep -q '^#!/'; then
-        rm -f "$installer"
-        log_error "starship installer does not look like a shell script"
-        return 1
-      fi
       sh "$installer" --yes
       local rc=$?
       rm -f "$installer"
@@ -158,115 +185,16 @@ _do_install() {
     atuin)
       local installer
       installer=$(umask 077 && mktemp)
-      if ! curl -fsSL -o "$installer" https://setup.atuin.sh; then
+      if ! download_verified_script https://setup.atuin.sh "$installer"; then
         rm -f "$installer"
         log_error "Failed to download atuin installer"
         return 1
       fi
-      if ! head -1 "$installer" | grep -q '^#!/'; then
-        rm -f "$installer"
-        log_error "atuin installer does not look like a shell script"
-        return 1
-      fi
       bash "$installer" --yes
       local rc=$?
       rm -f "$installer"
       return $rc
       ;;
-    nushell)
-      local arch tag ver
-      arch=$(uname -m)
-      tag=$(_gh_latest_tag "nushell/nushell")
-      ver="${tag#v}"
-      local tmp
-      tmp=$(mktemp -d)
-      curl -fsSL -o "$tmp/nu.tar.gz" \
-        "https://github.com/nushell/nushell/releases/download/${tag}/nu-${ver}-${arch}-unknown-linux-musl.tar.gz" &&
-        tar xzf "$tmp/nu.tar.gz" -C "$tmp" --strip-components=1 &&
-        install -m 755 "$tmp/nu" "$bin_dir/nu"
-      local rc=$?
-      rm -rf "$tmp"
-      return $rc
-      ;;
-    pueue)
-      local arch
-      arch=$(uname -m)
-      curl -fsSL -o "$bin_dir/pueue" \
-        "https://github.com/Nukesor/pueue/releases/latest/download/pueue-${arch}-unknown-linux-musl" &&
-        chmod +x "$bin_dir/pueue"
-      curl -fsSL -o "$bin_dir/pueued" \
-        "https://github.com/Nukesor/pueue/releases/latest/download/pueued-${arch}-unknown-linux-musl" &&
-        chmod +x "$bin_dir/pueued"
-      return $?
-      ;;
-    wasmtime)
-      local arch tag
-      arch=$(uname -m)
-      tag=$(_gh_latest_tag "bytecodealliance/wasmtime")
-      local tmp
-      tmp=$(mktemp -d)
-      # xz-utils required for .tar.xz extraction
-      command -v xz >/dev/null 2>&1 || sudo apt-get install -y -qq xz-utils >/dev/null 2>&1 || true
-      curl -fsSL -o "$tmp/wasmtime.tar.xz" \
-        "https://github.com/bytecodealliance/wasmtime/releases/download/${tag}/wasmtime-${tag}-${arch}-linux.tar.xz" &&
-        tar xJf "$tmp/wasmtime.tar.xz" -C "$tmp" --strip-components=1 &&
-        install -m 755 "$tmp/wasmtime" "$bin_dir/wasmtime"
-      local rc=$?
-      rm -rf "$tmp"
-      return $rc
-      ;;
-    sops)
-      local arch tag
-      arch=$(uname -m)
-      [[ "$arch" == "x86_64" ]] && arch="amd64"
-      [[ "$arch" == "aarch64" ]] && arch="arm64"
-      tag=$(_gh_latest_tag "getsops/sops")
-      curl -fsSL -o "$bin_dir/sops" \
-        "https://github.com/getsops/sops/releases/download/${tag}/sops-${tag}.linux.${arch}" &&
-        chmod +x "$bin_dir/sops"
-      return $?
-      ;;
-    hyperfine)
-      local arch tag
-      arch=$(uname -m)
-      tag=$(_gh_latest_tag "sharkdp/hyperfine")
-      local tmp
-      tmp=$(mktemp -d)
-      curl -fsSL -o "$tmp/hyperfine.tar.gz" \
-        "https://github.com/sharkdp/hyperfine/releases/download/${tag}/hyperfine-${tag}-${arch}-unknown-linux-musl.tar.gz" &&
-        tar xzf "$tmp/hyperfine.tar.gz" -C "$tmp" --strip-components=1 &&
-        install -m 755 "$tmp/hyperfine" "$bin_dir/hyperfine"
-      local rc=$?
-      rm -rf "$tmp"
-      return $rc
-      ;;
-    yazi)
-      local arch
-      arch=$(uname -m)
-      local url="https://github.com/sxyazi/yazi/releases/latest/download/yazi-${arch}-unknown-linux-musl.zip"
-      local tmp
-      tmp=$(mktemp -d)
-      command -v unzip >/dev/null 2>&1 || sudo apt-get install -y -qq unzip
-      curl -fsSL -o "$tmp/yazi.zip" "$url" &&
-        (cd "$tmp" && unzip -oq yazi.zip) &&
-        install -m 755 "$tmp"/yazi-*/yazi "$bin_dir/yazi"
-      local rc=$?
-      rm -rf "$tmp"
-      return $rc
-      ;;
-    zellij)
-      local arch
-      arch=$(uname -m)
-      local url="https://github.com/zellij-org/zellij/releases/latest/download/zellij-${arch}-unknown-linux-musl.tar.gz"
-      local tmp
-      tmp=$(mktemp -d)
-      curl -fsSL -o "$tmp/zellij.tar.gz" "$url" &&
-        tar xzf "$tmp/zellij.tar.gz" -C "$tmp" &&
-        install -m 755 "$tmp/zellij" "$bin_dir/zellij"
-      local rc=$?
-      rm -rf "$tmp"
-      return $rc
-      ;;
   esac
 
   # System package manager

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
+  ./tests/framework/test_runner.sh --jobs auto --integration-only
 }
 
 coverage_gate() {
@@ -123,11 +123,11 @@ fi
 
 printf 'Reliability Audit\n'
 printf 'Platform: %s\n' "$(platform_name)"
-printf 'Coverage floor: %s%%\n' "$min_coverage"
+printf 'Executable module-mapping floor: %s%%\n' "$min_coverage"
 
 run_step "Shell syntax" shell_syntax
 run_step "Unit suite" unit_tests
-run_step "Module coverage" coverage_gate
+run_step "Executable module mapping" coverage_gate
 run_step "Docs coverage" docs_coverage_gate
 run_step "Traceability coverage" traceability_gate
 run_step "Executable examples" example_gate

package/scripts/qa/scorecard-snapshot.sh

@@ -20,7 +20,7 @@
 
 set -euo pipefail
 
-REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+REPO_ROOT="${REPO_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
 cd "$REPO_ROOT"
 
 mode="write"
@@ -51,7 +51,7 @@ if ! command -v jq >/dev/null 2>&1; then
   exit 2
 fi
 
-payload="$(curl -sSfL "$api")" || {
+payload="$(curl --proto '=https' --tlsv1.2 -fsSL --connect-timeout 10 --max-time 30 "$api")" || {
   echo "Scorecard API unreachable: $api" >&2
   exit 2
 }
@@ -75,7 +75,7 @@ trap 'rm -f "$block"' EXIT
         | [.name, (.score|tostring), ((.reason // "") | gsub("\\|"; "\\|") | .[0:100])]
         | "| " + (. | join(" | ")) + " |"'
   # shellcheck disable=SC2016 # backticks here are markdown code-spans, not subshells
-  printf '\n_Refresh: `scripts/qa/scorecard-snapshot.sh` · CI check: `lint/scorecard-snapshot` (planned)._\n'
+  printf '\n_Refresh: `scripts/qa/scorecard-snapshot.sh` · Monitoring: `.github/workflows/scorecard.yml`._\n'
   printf '<!-- END scorecard-snapshot -->\n'
 } >"$block"
 

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