@sebastienrousseau/dotfiles 0.2.499 → 0.2.501

package/docs/guides/THEMING.md

@@ -0,0 +1,230 @@
+---
+render_with_liquid: false
+---
+{% raw %}
+
+# 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.
+{% endraw %}

package/docs/guides/TROUBLESHOOTING.md

@@ -0,0 +1,176 @@
+---
+render_with_liquid: false
+---
+
+# 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