@sebastienrousseau/dotfiles 0.2.481 → 0.2.500

package/docs/archive/EUXIS_2026_REVIEW.md

@@ -0,0 +1,119 @@
+# Euxis 2026 Architecture & Product Review
+
+This review translates the current dotfiles CLI stack into an Apple-tier product strategy:
+high power, near-zero cognitive load, and cross-platform parity (macOS, Linux, WSL).
+
+## Current state (what is already strong)
+
+- Unified entrypoint (`dot`) with modular command routing.
+- Good safety baseline (strict mode, governance, preflight checks).
+- Broad CI coverage with strong shell quality gates.
+- WSL support already exists but is distributed across scripts.
+
+## Gaps to close for Apple-tier quality
+
+### Performance and responsiveness
+
+- `dot doctor` scans broad filesystem paths and can feel slow on large homes.
+- Platform detection logic is duplicated across scripts.
+- Source directory resolution repeats file system probes in hot paths.
+
+### UX and cognitive load
+
+- Cross-platform behavior is implicit, not surfaced as a simple product contract.
+- Users still need to understand host/guest boundaries (especially WSL).
+- Onboarding signal is fragmented across docs and command help.
+
+### Product parity
+
+- No single abstraction layer for path conversion and host-native opening.
+- No first-class “platform parity” diagnostics in one section.
+
+## Implemented in this branch
+
+### 1) Platform abstraction layer
+
+Added `scripts/dot/lib/platform.sh` with:
+
+- `dot_platform_id`
+- `dot_host_os`
+- `dot_is_wsl`
+- `dot_path_to_unix`
+- `dot_path_to_native`
+- `dot_open_path`
+
+This centralizes platform semantics and removes per-script drift.
+
+### 2) Hot-path optimization in shared utils
+
+Updated `scripts/dot/lib/utils.sh`:
+
+- sources `platform.sh`
+- adds process-local source dir cache (`_DOT_SOURCE_DIR_CACHE`)
+- avoids repeated filesystem checks in repeated command flows
+
+### 3) Faster, clearer diagnostics
+
+Updated `scripts/diagnostics/doctor.sh`:
+
+- new **Platform** section (runtime + host + WSL bridge/fallback checks)
+- warns when running in `/mnt/*` under WSL (high IO latency path)
+- scoped symlink scan to standard roots only (`~/.config`, `~/.local`, `~/.ssh`)
+- adds explicit `dot` command resolution check
+
+### 4) Onboarding clarity
+
+Updated `README.md`:
+
+- added “60-second onboarding” with a clear success state
+
+### 5) Test coverage for new abstraction
+
+Added `scripts/tests/unit/test_dot_lib_platform.sh`:
+
+- existence + syntax + function presence + return contract checks
+
+## File-by-file next refactors (high ROI)
+
+1. `scripts/dot/commands/tools.sh`
+- Split `cmd_aliases` into submodule file.
+- Replace repeated `command -v` checks with cached capability map.
+
+2. `dot_config/zsh/dot_zshrc.tmpl`
+- Add startup budget guard (record startup time; warn >400ms).
+- Move optional integrations behind capability checks generated once/session.
+
+3. `scripts/ops/health-check.sh`
+- Import `platform.sh`, unify WSL/macOS/Linux branch logic.
+- Emit machine-readable JSON summary for UI frontends.
+
+4. `scripts/diagnostics/perf.sh`
+- Add percentile reporting (P50/P95 over 10 runs).
+- Add regression threshold with actionable remediation hints.
+
+## Product roadmap (prioritized)
+
+### P0 (1-2 weeks)
+
+- Platform abstraction adoption across all dot commands.
+- Bounded diagnostic scans everywhere (`find` scope + timeout).
+- “Single-screen health” command output format harmonization.
+
+### P1 (2-4 weeks)
+
+- Local state model for predictive UX (`~/.local/state/dotfiles/session.json`).
+- Adaptive hints (“next best action”) based on detected failures.
+- Non-blocking diagnostics execution with staged rendering.
+
+### P2 (4-8 weeks)
+
+- Optional Rust helper binary for path/process abstraction and fast JSON output.
+- WASM-compatible policy engine for deterministic config validation.
+- Cross-device state sync model (privacy-first, local-first defaults).
+
+## Apple-tier UX bar (acceptance criteria)
+
+- First successful install + health check in under 90 seconds.
+- `dot doctor` completes in under 700ms on warmed cache.
+- No user-facing distinction between macOS/Linux/WSL for core commands.
+- All failures return one-line remediation with direct command to fix.

package/docs/archive/MILESTONE_v0.2.493.md

@@ -0,0 +1,43 @@
+# Milestone v0.2.493 Scope
+
+This milestone keeps scope intentionally small and operationally focused.
+
+## Goals
+
+- Make post-merge verification a first-class workflow (`dot verify`).
+- Keep protected-branch CI deterministic (no unsigned bot commits on `master`).
+- Improve day-2 operator confidence with explicit verification guidance.
+
+## In Scope
+
+- [x] Add `dot verify` command routing in diagnostics module.
+  - `scripts/dot/commands/diagnostics.sh`
+  - `dot_local/bin/executable_dot`
+- [x] Add verification runner script.
+  - `scripts/diagnostics/verify.sh`
+  - Runs:
+    - `dot doctor`
+    - `dot status`
+    - `chezmoi diff`
+- [x] Update completion surfaces for new command.
+  - `dot_local/share/bash-completion/completions/dot`
+  - `dot_local/bin/executable_dot_completion`
+- [x] Harden sync-versions behavior for protected `master`.
+  - `.github/workflows/sync-versions.yml`
+  - `master` now verifies only; auto-sync commit job runs on non-master branches.
+- [x] Update docs and command references.
+  - `README.md`
+  - `docs/README.md`
+  - `docs/OPERATIONS.md`
+
+## Out of Scope
+
+- New security controls beyond existing baseline.
+- Major CLI redesign or command namespace reshuffle.
+- Release process automation changes outside sync-versions policy hardening.
+
+## Exit Criteria
+
+- `dot verify` returns non-zero on drift/issues and zero when healthy.
+- `sync-versions` workflow no longer attempts commits to protected `master`.
+- Relevant unit tests and targeted command tests pass.

package/docs/{PLAN.md → archive/PLAN.md}

@@ -85,7 +85,7 @@ Establish a "Trust Layer" for the dotfiles ecosystem, ensuring supply chain secu
 
 ## Changes
 - **SLSA & SBOM**: Implemented `security-release.yml` for provenance and SBOM generation.
-- **Signing**: Created `enable-signing` wizard alias for easy GPG/SSH configuration.
+- **Signing**: Created `enable-signing` wizard alias for streamlined GPG/SSH configuration.
 - **Immutability**: Created `lock-configs.sh` script and `lock-configs`/`unlock-configs` aliases.
 
 - **Immutability**: Created `lock-configs.sh` script and `lock-configs`/`unlock-configs` aliases.

package/docs/guides/INSTALL.md

@@ -0,0 +1,140 @@
+# Install
+
+Set up on macOS, Linux, or WSL in 3 to 5 minutes.
+
+**You will need:** `git` and `curl`.
+
+**Default shell:** Fish. You can change it after you install.
+
+## Install
+
+```bash
+bash -c "$(
+  curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh
+)"
+```
+
+Then restart your terminal or run `exec $SHELL`.
+
+## Verify
+
+```bash
+dot --version        # Confirm installation
+dot doctor           # Check shell, git, and tools
+dot help             # Browse available commands
+```
+
+## Choose a shell
+
+Fish is the default shell. To switch to Zsh or Nushell, edit `~/.dotfiles/.chezmoidata.toml`:
+
+```toml
+default_shell = "zsh"
+```
+
+Supported values: `zsh`, `fish`, `nushell`.
+
+Then apply the change:
+
+```bash
+dot apply
+```
+
+## Feature flags
+
+Turn optional tools on or off after setup. Edit `.chezmoidata.toml`:
+
+```toml
+[features]
+zsh = true         # Zsh shell configuration
+fish = true        # Fish shell configuration
+nushell = true     # Nushell configuration
+nvim = true        # Neovim IDE configuration
+tmux = true        # Terminal multiplexer
+nix = true         # Nix package manager integration
+```
+
+## Update
+
+```bash
+dot update
+```
+
+## Next steps
+
+1. Run `dot learn` to take a guided tour.
+2. Add your own tweaks in `~/.config/shell/custom/`.
+3. Read the [Utilities and `dot` CLI](../reference/UTILS.md) reference.
+
+---
+
+## Advanced
+
+### Local source install
+
+Clone the repo first, then run the installer from your local copy:
+
+```bash
+git clone https://github.com/sebastienrousseau/dotfiles.git ~/.dotfiles
+cd ~/.dotfiles
+./install.sh
+```
+
+### Minimal install
+
+Install only shells and core tools. This skips editor and terminal extras:
+
+```bash
+./install.sh --minimal
+```
+
+### Non-interactive install
+
+Use this mode for CI or scripts that run without user input:
+
+```bash
+DOTFILES_SILENT=1 DOTFILES_NONINTERACTIVE=1 \
+  bash -c "$(
+    curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh
+  )"
+```
+
+### Nix
+
+```bash
+nix develop ~/.dotfiles/nix
+nix profile install ~/.dotfiles/nix#dot-utils
+```
+
+### Offline bundle
+
+On a machine with internet access, create a bundle:
+
+```bash
+dot bundle ~/Downloads
+```
+
+Copy the archive to the target machine. Then unpack and install:
+
+```bash
+tar --zstd -xf dotfiles_offline_bundle_*.tar.zst -P
+cd ~/.dotfiles
+./install.sh --force
+```
+
+### Uninstall
+
+```bash
+chezmoi purge
+rm -rf ~/.dotfiles
+rm -rf ~/.local/share/chezmoi ~/.local/share/dotfiles.log
+```
+
+### Signed contributions
+
+All commits must be signed. See [Contributing](../../CONTRIBUTING.md) for details.
+
+---
+
+- [Troubleshooting](TROUBLESHOOTING.md)
+- [Support matrix](../reference/SUPPORT_MATRIX.md)

package/docs/{NEOVIM_IDE_GUIDE.md → guides/NEOVIM_IDE_GUIDE.md}

@@ -1,28 +1,28 @@
 # Neovim
 
-## Discover
-
-### 1. Modern Core
-- **Installation**: Uses Neovim Nightly (v0.11+) for the latest features and plugin compatibility.
-- **Configuration**: A modular and lazy-loaded configuration based on `lazy.nvim`.
-- **UI**: A beautiful and functional UI with a dashboard, status line, buffer line, and file explorer.
+## Modern Core
+- **Requirement**: Neovim >= 0.11.2. The config checks this at startup.
+- **Configuration**: Modular, lazy-loaded configuration based on `lazy.nvim`.
+- **Completion**: `blink.cmp` for fast, keystroke-level completion with LSP, snippets, and path sources.
+- **UI**: Snacks.nvim dashboard, notifications, status line, buffer line, and file explorer.
 - **LSP**: Full LSP support for diagnostics, code actions, and more, managed by `mason.nvim`.
 
-### 2. Language Support
-- **Rust**: Out-of-the-box support for Rust development with `rustaceanvim`.
-- **Python**: Full support for Python development with `basedpyright`, `ruff`, and `venv-selector`.
+## Language Support
+- **Rust**: Out-of-the-box support with `rustaceanvim`.
+- **Python**: Full support with `basedpyright`, `ruff`, and `venv-selector`.
 - **Web**: Support for web development with `prettier` and `eslint`.
 
-### 3. AI Integration
+## AI Integration
 - **Copilot**: `copilot.lua` for code completion. Run `:Copilot auth` to sign in.
 - **Copilot Chat**: AI sidebar for asking questions and getting help (`<leader>cc`).
 
-### 4. VS Code Parity
+## VS Code Parity
 - **Problem Panel**: `trouble.nvim` for a VS Code-like problems panel (`<leader>xx`).
 - **Search & Replace**: `nvim-spectre` for project-wide search and replace (`<leader>S`).
-- **Auto-Pairs**: Automatically closes brackets and pairs.
+- **Auto-Pairs**: Automatically closes brackets and pairs (via `blink.cmp` auto-brackets).
 - **TODOs**: Highlights `TODO` and `FIXME` comments.
 - **Session**: Auto-restores your last session.
+- **Snippets**: Native `vim.snippet` engine (Neovim 0.11+).
 
 ## Keybindings
 | Key | Action |

package/docs/guides/THEMING.md

@@ -0,0 +1,222 @@
+# Theming Guide
+
+The dotfiles ship a wallpaper-driven theme system that generates terminal color palettes directly from wallpaper images using K-Means clustering in CIELAB color space. One command changes the terminal, editor, window manager, GTK, desktop environment, wallpaper, and browser-facing color mode in under a second.
+
+Themes are not hand-crafted — they are extracted from whatever wallpapers are available on the system.
+
+## How Themes Work
+
+Wallpapers are the source of truth. The system discovers wallpapers from two locations:
+
+1. **System wallpapers** — platform-native (macOS `/System/Library/Desktop Pictures/`, Linux `/usr/share/backgrounds/`)
+2. **Custom wallpapers** — user-provided in `~/Pictures/Wallpapers/` (custom overrides system)
+
+`extract-theme.py` extracts dominant colors from each wallpaper using K-Means clustering in CIELAB color space, then generates a full terminal palette (16 ANSI colors, accent, bg/fg, panel, border) with WCAG contrast enforcement.
+
+`rebuild-themes.sh` orchestrates discovery → extraction → assembly into `.chezmoidata/themes.toml`. Themes are cached in `~/.cache/dotfiles/themes/` and only regenerated when wallpapers change.
+
+The `theme` key in `.chezmoidata.toml` controls the active theme. Every template references the active theme's data through `{{ $t := index .themes .theme }}`.
+
+## Switching Themes
+
+### Interactive Picker
+
+```bash
+dot theme
+```
+
+Opens an fzf picker listing every paired wallpaper theme (themes that have both `-dark` and `-light` variants). Two columns: **WALLPAPER** name and **SOURCE** (System or Custom). The current theme is marked with `✓` and `◀`. Select one and press Enter.
+
+### Direct Switch
+
+```bash
+dot theme tahoe-dark
+```
+
+Sets the theme immediately. Regenerates configs and reloads running applications.
+
+### Rebuild Themes
+
+```bash
+dot theme rebuild           # incremental (uses cache for unchanged wallpapers)
+dot theme rebuild --force   # full regeneration
+dot theme rebuild --list    # discover wallpapers without rebuilding
+```
+
+Discovers wallpapers from system + custom paths, runs K-Means extraction in parallel (4 jobs), caches generated themes in `~/.cache/dotfiles/themes/`, and writes `.chezmoidata/themes.toml`. Custom wallpapers override system wallpapers on name collision.
+
+### Under the Hood: dot-theme-sync
+
+`dot-theme-sync` handles the full switching pipeline:
+
+1. Writes the new theme name into `.chezmoidata.toml` (and `chezmoi.toml` if present).
+   If those files drift, `dot-theme-sync` now resynchronizes them before rendering because `chezmoi.toml` `[data]` overrides the source data file.
+2. Runs a targeted `chezmoi apply` on theme-dependent config files only -- much faster than a full apply.
+3. Signals running applications to reload and coordinates browser-facing theme state:
+
+```bash
+dot-theme-sync                    # Reload current theme
+dot-theme-sync macos-wave-light   # Switch to a new theme
+dot-theme-sync --full             # Full chezmoi apply instead of targeted
+```
+
+## What Changes
+
+Each theme switch touches these applications:
+
+| Application | Mechanism | What Changes |
+| :--- | :--- | :--- |
+| **Ghostty** | `chezmoi apply` + macOS app-support sync + DBus `reload-config` or runtime signal fallback | Background, foreground, all 16 ANSI colors, cursor |
+| **Tmux** | `chezmoi apply` + `source-file` | Status bar colors, pane borders, mode indicators |
+| **Niri** | `chezmoi apply` + `load-config-file` IPC | Window borders, focus ring, inactive tint |
+| **Desktop (macOS)** | `osascript` + `defaults write` + `killall` | System appearance (Light/Dark), accent color, highlight color; forces SystemUIServer/Dock/cfprefsd refresh |
+| **Wallpaper (macOS)** | `osascript` System Events | Desktop wallpaper set across all displays |
+| **Wallpaper (Linux)** | `gsettings` / `dms` / `swaybg` / `feh` | HEIC auto-converted to PNG; `picture-uri` and `picture-uri-dark` set separately |
+| **Desktop (Linux/GNOME)** | `chezmoi apply` + `gsettings` | Theme name, icon theme, color scheme preference |
+| **Safari / Chrome / Edge** | Native browser appearance follows desktop theme | Browser chrome stays aligned when using the default/native browser theme |
+| **Firefox** | `chezmoi apply` on `~/.config/firefox/user.js` | Website color scheme preference follows the active dot theme; link that file into a Firefox profile to enforce it |
+| **DMS** | `sed -i` on settings.json + IPC | Stock theme mapped to accent family, dark/light mode |
+| **Neovim** | `--remote-expr` Lua eval over socket | Colorscheme, style variant, background mode |
+| **VS Code** | `chezmoi apply` on `settings.json` | `workbench.colorTheme` value |
+| **Alacritty** | `chezmoi apply` | Full color block regeneration |
+| **Kitty** | `chezmoi apply` | Full color block regeneration |
+| **WezTerm** | `chezmoi apply` | Color scheme in Lua config |
+
+## Dark/Light Toggle
+
+```bash
+dot theme toggle
+```
+
+Toggles between the dark and light variant of the current theme family. A theme named `macos-tahoe-dark` toggles to `macos-tahoe-light`, and vice versa.
+
+## Theme Families
+
+Available themes depend on your system. Run `dot theme list` to see what's discovered. On macOS Sonoma, you'll see ~150+ themes from system wallpapers. Custom wallpapers in `~/Pictures/Wallpapers/` add more.
+
+### Rebuilding themes
+
+When wallpapers change (new system update, new custom wallpapers), regenerate:
+
+```bash
+dot theme rebuild          # Regenerate (uses cache for unchanged wallpapers)
+dot theme rebuild --force  # Force full regeneration
+dot theme rebuild --list   # List discovered wallpapers without rebuilding
+```
+
+## What works without wallpapers
+
+Theme switching is a two-tier system:
+
+**Core (always works)** — ships in the repo, no setup needed:
+- Terminal colors (Ghostty, Alacritty, Kitty, WezTerm, tmux)
+- Editor themes (Neovim colorscheme, VS Code)
+- macOS dark/light mode and accent color
+- Linux GNOME color-scheme, GTK theme, icon theme
+- Browser color mode (Safari, Chrome, Firefox)
+
+**Wallpapers (optional)** — user-provided, enhances the theme:
+- Desktop wallpaper matched to the active theme
+- Requires `~/Pictures/Wallpapers/` with files named `macos-NAME-dark.heic`
+
+If no wallpapers are present, `dot theme` applies all core changes and skips the wallpaper step. No errors, no manual config.
+
+## Wallpapers (optional)
+
+Wallpapers are not shipped in the repo. Each user sources their own and places them in `~/Pictures/Wallpapers/`:
+
+```
+macos-tahoe-dark.heic
+macos-tahoe-light.heic
+```
+
+The naming convention is `macos-NAME-APPEARANCE.heic` (or `.jpg`/`.png`). The theme picker marks themes with matching wallpapers as `[W]`.
+
+### Wallpaper guidelines
+
+- **Resolution**: 6016x6016 recommended (matches Apple's native resolution)
+- **Format**: `.heic` preferred on macOS, `.png`/`.jpg` also supported
+- **Brightness**: dark/light pairs targeting a golden ratio (1.618) relationship give balanced contrast across displays
+
+### Platform behavior
+
+| Platform | Wallpaper support | Mechanism |
+|---|---|---|
+| **macOS** | `.heic`, `.jpg`, `.png` | `osascript` (all desktops) |
+| **Linux (GNOME)** | `.png`, `.jpg` (`.heic` auto-converted) | `gsettings picture-uri` + `picture-uri-dark` |
+| **Linux (Wayland)** | `.png`, `.jpg` (`.heic` auto-converted) | `swaybg`, `feh`, or Niri/DMS IPC |
+| **WSL** | Not applicable | No compositor; terminal colors still apply |
+
+On Linux, `.heic` files are automatically converted to `.png` using `magick`, `heif-convert`, or `convert` (whichever is available). The `.png` is cached and only regenerated when the source `.heic` changes.
+
+### Using your OS default wallpapers
+
+If you don't provide custom wallpapers, your OS keeps its current desktop wallpaper. The theme still applies all color changes (terminal, editor, accent, dark/light mode). This is the expected default for most users.
+
+## Build Artifacts
+
+All build caches (Cargo, Go, pip, uv, Zig) are redirected to `/tmp/builds/` via environment variables in `mise.toml` and `cargo/config.toml`. The directory is created on shell init via `fish/conf.d/env.fish`. Build artifacts are cleared on reboot.
+
+## Troubleshooting
+
+### Theme switch did not apply
+
+Run a full apply to force all configs:
+
+```bash
+dot-theme-sync --full
+```
+
+### Ghostty did not reload
+
+Ghostty reloads via DBus (`com.mitchellh.ghostty` / `reload-config`). If DBus is unavailable, the fallback sends `SIGUSR2` to the main process and also matches the macOS app bundle path when needed. Verify Ghostty is running:
+
+```bash
+pgrep -x ghostty
+```
+
+On macOS, Ghostty may also read `~/Library/Application Support/com.mitchellh.ghostty/config`. `dot-theme-sync` now mirrors the regenerated XDG config into that location before reloading so the app-support override cannot keep an older palette active.
+
+### Neovim did not change colors
+
+`dot-theme-sync` finds Neovim server sockets at `/tmp/nvim*/0` and `$XDG_RUNTIME_DIR/nvim.*.0`. If Neovim runs with a custom `--listen` path, the auto-discovery misses it. Restart Neovim to pick up the new theme from the regenerated config.
+
+### GTK theme looks wrong
+
+GTK theme names must match installed themes exactly. Catppuccin themes use names like `catppuccin-mocha-blue-standard+default`. Install the matching GTK theme package or fall back to `Adwaita-dark` / `Adwaita`.
+
+### macOS accent or appearance did not update
+
+`dot-theme-sync` applies macOS appearance using `osascript` and accent via:
+
+```bash
+defaults write -g AppleAccentColor -int <value>
+```
+
+`dot-theme-sync` now kills `cfprefsd`, `SystemUIServer`, `Dock`, and `System Settings` after writing accent/highlight defaults to force an immediate refresh. If the UI still does not update, close and reopen System Settings.
+
+### Browser theme did not change
+
+Safari, Chrome, and Edge are coordinated through the desktop theme, so custom browser themes can override what `dot-theme-sync` is trying to align. Switch those browsers back to their native/default theme if you want them to track macOS or GTK automatically.
+
+Firefox uses the managed file at `~/.config/firefox/user.js`. Link that file into your active Firefox profile as `user.js` if you want `dot-theme-sync` to control website `prefers-color-scheme` behavior:
+
+```bash
+ln -sf ~/.config/firefox/user.js ~/.mozilla/firefox/<profile>/user.js
+```
+
+### tmux shows old colors
+
+Tmux reloads via `source-file`. If TPM plugins override colors, run:
+
+```bash
+tmux source-file ~/.config/tmux/tmux.conf
+```
+
+### Checking the active theme
+
+```bash
+grep '^theme = ' ~/.dotfiles/.chezmoidata.toml
+```
+
+This prints the current theme name. Cross-reference with `dot theme list` for available options.

package/docs/{TROUBLESHOOTING.md → guides/TROUBLESHOOTING.md}

@@ -13,6 +13,7 @@ Quick checks for common issues.
 - Re-run `chezmoi apply` to re-sync state.
 - Check for merge conflicts: `chezmoi diff`
 - If hooks fail, check `~/.local/share/dotfiles.log` for details.
+- For non-interactive sessions, force apply to avoid TTY prompts: `DOTFILES_NONINTERACTIVE=1 dot apply --force`
 
 **Problem:** Packages fail to install
 - macOS: Verify Homebrew is installed and up to date (`brew update`)
@@ -31,6 +32,19 @@ Quick checks for common issues.
 - Source your shell config: `source ~/.zshrc`
 - Verify the relevant tool is installed
 
+**Problem:** `dot doctor` prints a directory listing instead of diagnostics
+- This usually means `dot` was shadowed by a navigation alias in the current shell session.
+- Check resolution: `type -a dot`
+- Fix current session: `unalias dot 2>/dev/null || true && exec zsh`
+- Validate after reload: `dot doctor`
+
+**Problem:** Zsh reports it cannot write `.zwc` files
+- Cause: stale read-only zsh cache files after an upgrade.
+- Remove stale caches:
+  - `find ~/.config/shell ~/.config/zsh -type f -name '*.zwc' -delete`
+- Reload shell: `exec zsh`
+- Re-run health checks: `dot doctor`
+
 **Problem:** Shell crashes on startup
 - Temporarily move `~/.zshrc` and retry to isolate the fault
 - Check for syntax errors: `zsh -n ~/.zshrc`
@@ -88,6 +102,28 @@ Quick checks for common issues.
 - Review shell history size in atuin config
 - Disable unused plugins
 
+## Common infrastructure failures
+
+**Problem:** Nix isn't installed or commands not found
+- Ensure you have followed the installation guide: `curl -L https://nixos.org/nix/install | sh`
+- On Linux, you might need to enable experimental features in `~/.config/nix/nix.conf`:
+  `experimental-features = nix-command flakes`
+- Verify the daemon is running: `ps aux | grep nix-daemon`
+
+**Problem:** Systemd isn't available (mostly WSL2)
+- Dotfiles functions that rely on systemd (like `pueue` management) will fallback to direct execution.
+- To enable systemd in WSL2, add this to `/etc/wsl.conf` (requires Windows 11 or latest WSL):
+  ```ini
+  [boot]
+  systemd=true
+  ```
+- Restart WSL: `wsl.exe --shutdown`
+
+**Problem:** GPG or SSH signing fails
+- Check if your key is present: `gpg --list-secret-keys` or `ssh-add -l`
+- Ensure `GPG_TTY` is set (dotfiles does this automatically in `rc.d`).
+- For hardware keys (Yubikey), ensure `pcscd` is running on Linux.
+
 ## Advanced Troubleshooting
 
 ### WSL2 and Nix Integration Issues