@sebastienrousseau/dotfiles 0.2.499 → 0.2.500

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.
@@ -96,7 +96,7 @@ Establish a "Trust Layer" for the dotfiles ecosystem, ensuring supply chain secu
 Enable the system to self-diagnose and repair configuration drift.
 
 ## Changes
-- **Scripts**: Created `scripts/doctor.sh` for system health checks.
+- **Scripts**: Created `scripts/diagnostics/doctor.sh` for system health checks.
 - **Aliases**: Added `dot doctor`, `dot drift` (`chezmoi verify`), and `dot heal` (`chezmoi apply`).
 
 # Phase 51: Regulatory Compliance [COMPLETED]
@@ -144,7 +144,7 @@ Prepare the dotfiles for system-wide deployment and ensure strict adherence to s
 ## Proposed Changes
 - **XDG Compliance**: Audit `00-default.paths.sh` to ensure all standard XDG variables are exported.
 - **Vendor Hooks**: Update `dot_zshrc.tmpl` to source system-level overrides from `/etc/dotfiles/defaults.d/` (Simulates "site-local" config).
-- **Bundling**: Create `scripts/package.sh` to create a distributable tarball and scaffold `.deb`/`.pkg` generation logic.
+- **Bundling**: Create `scripts/core/package.sh` to create a distributable tarball and scaffold `.deb`/`.pkg` generation logic.
 
 # Phase 24: The Universal Installer (Zero-Dependency) [COMPLETED]
 
@@ -158,4 +158,4 @@ Provide a frictionless, "one-curl" onboarding experience and capabilities to dep
     3.  Initializes the dotfiles repo.
     4.  Runs `chezmoi apply`.
     5.  Uses ANSI colors for a polished "TUI" feel.
-- **Teleportation**: `scripts/teleport.sh` using `chezmoi archive` piped to SSH to ephemeralize configs on remote servers (e.g., `dot teleport user@server`).
+- **Teleportation**: `scripts/ops/teleport.sh` using `chezmoi archive` piped to SSH to ephemeralize configs on remote servers (e.g., `dot teleport user@server`).

package/docs/archive/REPO_AUDIT.md

@@ -0,0 +1,23 @@
+# Repo Audit
+
+## Source of truth
+- `~/.dotfiles` (chezmoi source directory)
+
+## Key directories
+- `.chezmoitemplates/` - templated aliases, functions, paths
+- `dot_config/` - configs mapped into `~/.config`
+- `dot_local/` - binaries and local data (e.g., `dot` CLI)
+- `scripts/` - diagnostics, tests, tooling
+- `tests/` - sandbox Dockerfile
+- `nix/` - optional Nix toolchain
+
+## Notable dependencies
+- `chezmoi`
+- `zsh`, `starship`
+- `neovim`
+- `ripgrep`, `fd`, `bat`, `fzf`, `zoxide`
+- `lazygit`
+
+## Notes
+- Repo-only files excluded via `.chezmoiignore`.
+- Secrets are handled via `age` + `dot secrets` (see `docs/SECRETS.md`).

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/guides/NEOVIM_IDE_GUIDE.md

@@ -0,0 +1,52 @@
+# Neovim
+
+## 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`.
+
+## 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`.
+
+## 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`).
+
+## 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 (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 |
+| --- | --- |
+| `<Space>ff` | Find Files |
+| `<Space>fg` | Grep (Search) text |
+| `<Space>fb` | File browser |
+| `<Space>fp` | Projects |
+| `<Space>e` | Toggle File Explorer |
+| `<Space>a` | Add file to Harpoon |
+| `<Ctrl>e` | Open Harpoon menu |
+| `gd` | Go to Definition |
+| `gr` | Go to References |
+| `<leader>ca` | Code actions |
+| `<leader>cf` | Format code |
+| `<leader>cr` | Rename symbol |
+| `<leader>tt` | Toggle terminal |
+| `<leader>tn` | Test nearest |
+| `<leader>tf` | Test file |
+| `<leader>ts` | Test suite |
+| `<F5>` | Continue (Debug) |
+| `<F10>` | Step over (Debug) |
+| `<F11>` | Step into (Debug) |
+| `<F12>` | Step out (Debug) |
+| `<leader>cc` | Toggle Copilot Chat |
+| `<leader>xx` | Toggle Diagnostics (Trouble) |
+| `<leader>S` | Toggle Spectre (Search/Replace) |

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/guides/TROUBLESHOOTING.md

@@ -0,0 +1,148 @@
+# Troubleshooting
+
+Quick checks for common issues.
+
+## Install and update
+
+**Problem:** Install script fails immediately
+- Verify that `git` and `curl` are installed.
+- Check internet connectivity.
+- Try running with verbose output: `bash -x install.sh`
+
+**Problem:** Chezmoi apply fails
+- 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`)
+- Linux: Run `sudo apt-get update` first
+- Verify you have sufficient permissions
+
+## Shell startup
+
+**Problem:** Shell is slow to start
+- Run `dot benchmark` to measure startup time
+- Profile with `zsh -x` to trace startup
+- Check for slow plugins or large history files
+
+**Problem:** Aliases or functions not available
+- Run `chezmoi apply` to regenerate config files
+- 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`
+- Review recent changes: `chezmoi diff`
+
+## Secrets and encryption
+
+**Problem:** Encrypted files fail to decrypt
+- Confirm `~/.config/chezmoi/key.txt` exists.
+- Verify the key matches the one used for encryption.
+- Re-initialize with `dot secrets-init` if needed.
+
+**Problem:** Age encryption not working
+- Verify `age` is installed: `command -v age`
+- Check key permissions: `ls -la ~/.config/chezmoi/key.txt` (should be 600)
+
+## Neovim
+
+**Problem:** Plugins fail to load
+- Run `:checkhealth` in Neovim
+- Update plugins: `:Lazy sync`
+- Check for missing dependencies (node, python, etc.)
+
+**Problem:** LSP not working
+- Install required language servers
+- Check `:LspInfo` for status
+- Review `:LspLog` for errors
+
+## Git
+
+**Problem:** Git aliases not working
+- Check if Git config is applied: `git config --list`
+- Re-apply dotfiles: `chezmoi apply`
+
+**Problem:** Delta (diff pager) not showing colors
+- Verify `delta` is installed
+- Confirm your terminal supports 256 colors
+
+## Kubernetes tools
+
+**Problem:** kubectl context issues
+- List contexts: `kubectl config get-contexts`
+- Switch context: `kubectx <context-name>`
+- Check kubeconfig: `echo $KUBECONFIG`
+
+**Problem:** Minikube won't start
+- Verify Docker is running
+- Try: `minikube delete && minikube start`
+- Check logs: `minikube logs`
+
+## Performance
+
+**Problem:** High memory usage
+- Look for runaway processes: `htop` or `btop`
+- 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
+
+For complex WSL2 edge cases, Nix integration problems, and recovery procedures, see the comprehensive guide:
+**[WSL2 & Nix Troubleshooting Guide](WSL2_NIX_TROUBLESHOOTING.md)**
+
+This guide covers:
+- WSL2 filesystem and networking edge cases
+- Nix installation and flake management issues
+- Complete system recovery procedures
+- Performance optimization for WSL2/Nix environments
+- Cross-platform migration scenarios
+
+## Still stuck
+
+Open an issue with:
+- OS + version
+- Output of `dot doctor` (if available)
+- Relevant log snippets from `~/.local/share/dotfiles.log`
+- Steps to reproduce the issue
+- For WSL2/Nix issues: Include diagnostic report from the advanced guide