@sebastienrousseau/dotfiles 0.2.481 → 0.2.500

package/docs/manual/02-tutorials/01-first-install.md

@@ -0,0 +1,192 @@
+# Tutorial: First Install
+
+End-to-end installation and verification, from zero to a fully-working environment in under 5 minutes.
+
+## Prerequisites
+
+- macOS 14+, Ubuntu/Debian 20.04+, Arch (rolling), Fedora 39+, or WSL2 on Windows 11
+- `git` and `curl` installed
+- Shell access (Zsh, Fish, or Bash)
+- Optional but recommended: SSH key for signing commits
+
+## Step 1: Run the Installer
+
+```sh
+bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh)"
+```
+
+The installer:
+1. Verifies prerequisites (`git`, `curl`, write access to `~`)
+2. Downloads chezmoi via the SHA256-verified installer
+3. Clones the dotfiles source to `~/.dotfiles`
+4. Runs `chezmoi init` to prompt for per-machine settings
+5. Runs `chezmoi apply` with progress output
+
+Expected output:
+
+```
+[install] Verifying prerequisites
+[install] Installing chezmoi (verified SHA256)
+[install] Cloning source to ~/.dotfiles
+[install] Running chezmoi init (interactive)
+  Git email: you@example.com
+  Machine preset [macbook-t2]:
+  Default theme [tahoe-dark]:
+  Default shell [fish]:
+[install] Applying configuration (180 files)
+[install] ✓ Installation complete
+```
+
+## Step 2: Verify
+
+Open a new shell and run:
+
+```sh
+dot doctor
+```
+
+Expected output:
+
+```
+◈ DOTFILES
+Dot • Diagnostics
+
+--- Health Check ---
+  ✓ Paths             ~/.local/bin, mise shims present
+  ✓ Tools             git, chezmoi, mise installed
+  ✓ Chezmoi           clean (no drift)
+  ✓ Shell             fish (500ms startup)
+  ✓ Security          SSH key present, Age key present
+  ✓ Portability       LC_ALL=en_US.UTF-8, TERM=xterm-256color
+
+Score: 98/100
+```
+
+Any warnings will be accompanied by a suggested fix.
+
+## Step 3: Take the Tour
+
+```sh
+dot learn
+```
+
+An interactive walkthrough covering:
+
+- Shell basics and aliases
+- Secrets workflow
+- Theme switching
+- Performance tuning
+- Security hardening
+
+Each section takes 30-60 seconds. You can skip sections or exit at any time.
+
+## Step 4: Customize
+
+### Per-Machine Settings
+
+Edit `~/.config/chezmoi/chezmoi.toml`:
+
+```toml
+[data]
+machine = "macbook-t2"       # see .chezmoidata/hardware.toml for presets
+theme = "tahoe-dark"         # see `dot theme list`
+default_shell = "fish"       # fish, zsh, bash
+terminal_font_family = "JetBrainsMono Nerd Font"
+terminal_font_size = 12
+```
+
+### Feature Flags
+
+Edit `.chezmoidata.toml` in the source directory (`~/.dotfiles/.chezmoidata.toml`):
+
+```toml
+[features]
+dms = false                  # Dank Material Shell (Niri)
+linux_desktop = false        # Linux-specific desktop configs
+waybar = false               # Waybar status bar
+```
+
+After editing, apply:
+
+```sh
+dot apply
+```
+
+## Step 5: Add Your Identity
+
+If you have an SSH key, configure signed commits:
+
+```sh
+git config --global user.signingkey ~/.ssh/id_ed25519.pub
+git config --global commit.gpgsign true
+git config --global gpg.format ssh
+git config --global gpg.ssh.allowedSignersFile ~/.ssh/allowed_signers
+```
+
+Add your own key to `~/.ssh/allowed_signers`:
+
+```
+you@example.com ssh-ed25519 AAAA...
+```
+
+Test:
+
+```sh
+cd ~/.dotfiles
+git commit --allow-empty -m "test: signature"
+git verify-commit HEAD
+# Good "git" signature for you@example.com
+```
+
+## Step 6: First Theme Switch
+
+```sh
+dot theme
+```
+
+A picker opens showing all paired wallpaper themes on your system. Select one and press Enter. The terminal, editor, desktop wallpaper, and macOS accent color update in about 3 seconds.
+
+## Troubleshooting
+
+If `dot doctor` shows failures:
+
+```sh
+dot heal      # auto-fix common issues
+dot heal -n   # dry-run first to see what would change
+```
+
+If the installation is broken beyond repair:
+
+```sh
+dot rollback  # restore the previous known-good state
+```
+
+If `dot doctor` still fails after heal + rollback, check:
+
+- `~/.local/state/dotfiles/install.log` — installer log
+- `~/.local/state/dotfiles/heal.log` — heal attempts
+- `chezmoi doctor` — chezmoi-specific diagnostics
+
+Still stuck? See [Cookbook: Troubleshooting](../04-cookbook/02-troubleshooting.md).
+
+## What Got Installed
+
+After `dot doctor` reports a healthy score, you have:
+
+| Surface | What's There |
+|:---|:---|
+| **Shell** | Fish (default), Zsh, Nushell, Bash all configured with cached init |
+| **Editor** | Neovim with lazy.nvim + LSP + theme-synced colorscheme |
+| **Terminal** | Ghostty/Alacritty/Kitty/WezTerm configs (pick whichever is installed) |
+| **Git** | Signed commits, delta diff, conventional commit template |
+| **AI tooling** | Claude Code, Codex, Copilot CLI, Gemini CLI via mise |
+| **Secret store** | Age key, SOPS config, `dot secrets` command ready |
+| **Security** | Gitleaks, detect-secrets baseline, signed attestation log |
+| **Theme engine** | K-Means wallpaper extractor, system + custom wallpaper discovery |
+
+## Next
+
+- [Tutorial: Add a Wallpaper → Theme](02-add-wallpaper.md)
+- [Tutorial: Create a Machine Profile](03-create-profile.md)
+- [Tutorial: Encrypt a Secret](04-encrypt-secret.md)
+- [Cookbook: 30+ recipes](../04-cookbook/01-recipes.md)

package/docs/manual/02-tutorials/02-add-wallpaper.md

@@ -0,0 +1,211 @@
+# Tutorial: Add a Wallpaper → Theme
+
+Drop an image. Get a fully-WCAG-AAA terminal theme.
+
+## Prerequisites
+
+- Dotfiles installed (see [First Install](01-first-install.md))
+- `magick` (ImageMagick) and `python3` available (installed by default)
+- Optional: `heif-enc` for creating dynamic HEIC (`brew install libheif`)
+
+## Option A: Drop a Static Image
+
+The simplest path: place a wallpaper in `~/Pictures/Wallpapers/` and rebuild.
+
+```sh
+cp ~/Downloads/my-wallpaper.jpg ~/Pictures/Wallpapers/mytheme-dark.jpg
+cp ~/Downloads/my-wallpaper-light.jpg ~/Pictures/Wallpapers/mytheme-light.jpg
+
+dot theme rebuild
+```
+
+Expected output:
+
+```
+Discovering wallpapers...
+  Found: 126 system, 26 custom (152 total)
+
+Generating themes...
+  Processing 2 wallpapers (4 parallel jobs)...
+  mytheme-dark                             [custom] ✓
+  mytheme-light                            [custom] ✓
+
+Results: 2 processed, 150 cached, 0 failed
+
+Assembling themes.toml...
+  Written: ~/.dotfiles/.chezmoidata/themes.toml (608 theme sections)
+
+Done. Run 'dot theme list' to see available themes.
+```
+
+Switch to the new theme:
+
+```sh
+dot theme mytheme-dark
+```
+
+## Option B: Dynamic HEIC (Recommended)
+
+Apple's dynamic HEIC format stores both dark and light variants in a single file with metadata that macOS uses to auto-switch appearance. This is the native format for Apple system wallpapers.
+
+### Create a Dynamic HEIC From a Pair
+
+If you have `mytheme-dark.jpg` + `mytheme-light.jpg`:
+
+```sh
+bash scripts/theme/merge-wallpaper.sh mytheme
+```
+
+This:
+1. Resizes both to 6016×6016 (preserving aspect ratio, center-cropped)
+2. Encodes both into a single `.heic` via `heif-enc`
+3. Injects `apple_desktop:apr` XMP metadata (image 0 = light, image 1 = dark)
+4. Writes to `~/Pictures/Wallpapers/mytheme.heic`
+5. Removes the two source files
+
+Verify:
+
+```sh
+heif-info ~/Pictures/Wallpapers/mytheme.heic
+# image: 6016x6016 (id=1), primary    ← light
+# image: 6016x6016 (id=4)              ← dark
+# metadata:
+#   XMP: 2473 bytes                    ← appearance mapping
+```
+
+### Rebuild Themes
+
+```sh
+dot theme rebuild
+# mytheme-light  [custom] ✓
+# mytheme-dark   [custom] ✓
+```
+
+The engine extracts each frame independently and generates paired themes.
+
+## Option C: Golden Ratio Brightness (Advanced)
+
+For best perceived contrast between your dark and light themes, target a brightness ratio of ~1.6× (the golden ratio, approximately 1.618).
+
+Measure:
+
+```sh
+magick ~/Pictures/Wallpapers/mytheme-dark.jpg -resize 1x1\! -format '%[fx:mean]' info:
+# 0.30
+
+magick ~/Pictures/Wallpapers/mytheme-light.jpg -resize 1x1\! -format '%[fx:mean]' info:
+# 0.48
+# Ratio: 0.48 / 0.30 = 1.6   ← ideal
+```
+
+Adjust a pair if the ratio is off:
+
+```sh
+# Darken light to 0.485 brightness
+mod=$(python3 -c "print(int((0.485 / 0.60) * 100))")  # current mean = 0.60
+magick input.jpg -modulate ${mod},100,100 output.jpg
+```
+
+## Option D: Install System Wallpapers (Already-Available)
+
+macOS ships dozens of wallpapers you can use directly — no download needed.
+
+List what's available:
+
+```sh
+dot theme rebuild --list
+```
+
+Output:
+
+```
+NAME                        SOURCE     PATH
+----                        ------     ----
+big-sur-graphic-dark        system     /System/Library/Desktop Pictures/.thumbnails/Big Sur Graphic Dark.heic
+big-sur-graphic-light       system     /System/Library/Desktop Pictures/.thumbnails/Big Sur Graphic Light.heic
+dome-dark                   system     /System/Library/Desktop Pictures/.thumbnails/Dome Dark.heic
+dome-light                  system     /System/Library/Desktop Pictures/.thumbnails/Dome Light.heic
+sonoma-dark                 system     /System/Library/Desktop Pictures/.thumbnails/Sonoma Dark.heic
+...
+Total: 152 wallpapers
+```
+
+Switch to any system wallpaper:
+
+```sh
+dot theme dome-dark
+```
+
+The engine extracts Dome Dark's dominant colors, generates a palette, and applies it to every surface.
+
+## Verifying the Result
+
+After a switch, check the applied colors:
+
+```sh
+# See the current theme's palette
+grep -A30 "^\[themes.mytheme-dark\]" ~/.dotfiles/.chezmoidata/themes.toml
+```
+
+Check WCAG compliance (always passes for generated themes):
+
+```sh
+bash tests/unit/theme/test_themes_toml.sh
+# RESULTS: 11:11:0 (11 tests, 11 passed, 0 failed)
+```
+
+Verify the applied wallpaper:
+
+```sh
+# macOS
+osascript -e 'tell application "System Events" to get picture of every desktop'
+
+# Linux (GNOME)
+gsettings get org.gnome.desktop.background picture-uri
+gsettings get org.gnome.desktop.background picture-uri-dark
+```
+
+## Troubleshooting
+
+### Low Contrast on Both Variants
+
+Your wallpaper pair doesn't have enough brightness difference. The theme will still generate but `dot theme list` may filter it from the picker. Adjust the source images to increase separation (brighter light variant, darker dark variant).
+
+### K-Means Failed to Converge
+
+Rare, but possible with images that are nearly solid color. The engine uses a seeded RNG and 3 runs — if all 3 fail, the output theme is skipped. Fix: use a more chromatic source image.
+
+### Wallpaper Doesn't Apply on Linux
+
+Check your desktop environment:
+
+- **GNOME** — uses `gsettings picture-uri` (HEIC auto-converted to PNG)
+- **KDE** — uses `plasma-apply-wallpaperimage`
+- **Niri** — uses DMS IPC or `swaybg`
+- **i3/sway (no DE)** — falls back to `feh`
+
+If none are detected, set `$WALLPAPER_COMMAND` in `~/.config/dotfiles/config`.
+
+### The Dark/Light Auto-Switch Isn't Working on macOS
+
+The `apple_desktop:apr` metadata may be missing. Verify:
+
+```sh
+magick ~/Pictures/Wallpapers/mytheme.heic -format '%[XMP]' info: | grep apple_desktop
+```
+
+If empty, re-run `merge-wallpaper.sh` — the XMP injection step may have failed due to missing `exiftool`.
+
+## Summary
+
+You've added a custom wallpaper, generated a WCAG AAA theme from it, and verified cross-surface application. You can now:
+
+- Add more wallpapers to build a library
+- Share your wallpaper directory across fleet hosts (it's gitignored by default)
+- Use `dot theme toggle` to swap dark↔light of your current family
+
+## Next
+
+- [Concept: The Theme Engine](../01-concepts/03-theme-engine.md) — deep dive
+- [Tutorial: Create a Profile](03-create-profile.md)
+- [Cookbook: Theming Recipes](../04-cookbook/01-recipes.md)

package/docs/manual/02-tutorials/03-create-profile.md

@@ -0,0 +1,238 @@
+# Tutorial: Create a Machine Profile
+
+Machine profiles tell chezmoi how to render templates differently on each host — display scale, keyboard layout, performance preset, available features.
+
+## When to Use a Profile
+
+- You have more than one host (laptop + desktop, work + personal)
+- Your hardware differs materially (HiDPI laptop vs 1080p external, ARM vs x86)
+- Certain features only apply to specific setups (Niri on Wayland, AeroSpace on macOS)
+
+## Step 1: Choose or Create a Preset
+
+Presets live in `.chezmoidata/hardware.toml`:
+
+```toml
+[hardware.macbook-t2]
+display_scale = 2.0
+kbd_layout = "qwerty"
+modifier_mode = "left-cmd-control"
+perf_profile = "laptop"
+wm = "aerospace"
+[hardware.macbook-t2.features]
+retina = true
+touchid = true
+
+[hardware.surface-pro]
+display_scale = 1.5
+kbd_layout = "colemak-dh"
+modifier_mode = "standard"
+perf_profile = "laptop"
+wm = "niri"
+[hardware.surface-pro.features]
+touch = true
+pen = true
+```
+
+If an existing preset fits: use its name. Otherwise, add a new one.
+
+## Step 2: Select the Preset for This Host
+
+Edit `~/.config/chezmoi/chezmoi.toml`:
+
+```toml
+[data]
+machine = "surface-pro"      # choose from .chezmoidata/hardware.toml
+theme = "dome-dark"
+default_shell = "fish"
+terminal_font_family = "JetBrainsMono Nerd Font"
+terminal_font_size = 11       # larger for HiDPI, smaller for dense screens
+```
+
+`chezmoi.toml` is **not** in the repository — each host has its own. Generated by `chezmoi init` on first install.
+
+## Step 3: Reference the Preset in Templates
+
+Inside any `.tmpl` file:
+
+```go
+{{- $hw := index .hardware .machine }}
+
+# Ghostty config — uses machine-specific font size
+font-family = "{{ .terminal_font_family }}"
+font-size = {{ .terminal_font_size }}
+
+# DPI-aware settings
+{{ if eq $hw.display_scale 2.0 }}
+window-decoration = false
+{{ else }}
+window-decoration = true
+{{ end }}
+
+# Feature-gated config
+{{ if $hw.features.touch }}
+mouse-scroll-multiplier = 3
+{{ end }}
+```
+
+After editing the template, run `chezmoi apply` or `dot apply`.
+
+## Step 4: Add a New Preset
+
+Suppose you have a new mini PC. Add to `.chezmoidata/hardware.toml`:
+
+```toml
+[hardware.my-nuc]
+display_scale = 1.0           # external 1440p
+kbd_layout = "qwerty"
+modifier_mode = "standard"
+perf_profile = "desktop"
+wm = "gnome"
+[hardware.my-nuc.features]
+multi-monitor = true
+gaming = true
+```
+
+Then on that host:
+
+```toml
+# ~/.config/chezmoi/chezmoi.toml
+[data]
+machine = "my-nuc"
+```
+
+Apply:
+
+```sh
+dot apply
+```
+
+Templates automatically pick up the new preset data.
+
+## Step 5: Per-Preset Feature Flags
+
+Feature flags in `.chezmoidata.toml` can be gated by preset:
+
+```toml
+# .chezmoidata.toml — defaults for all hosts
+[features]
+dms = false
+linux_desktop = false
+waybar = false
+```
+
+Override per-preset in `.chezmoidata/hardware.toml`:
+
+```toml
+[hardware.surface-pro.features]
+touch = true
+pen = true
+dms = true                    # override feature default
+waybar = true
+```
+
+In templates:
+
+```go
+{{- $hw := index .hardware .machine }}
+{{- $features := mergeOverwrite .features $hw.features }}
+
+{{ if $features.waybar }}
+# ... waybar-specific config ...
+{{ end }}
+```
+
+## Example: Font Size by Preset
+
+A single Ghostty config that renders correctly on every host:
+
+```go
+# dot_config/ghostty/config.tmpl
+{{- $hw := index .hardware .machine }}
+
+theme = {{ .theme }}
+font-family = "{{ .terminal_font_family }}"
+
+# DPI-aware font sizing
+{{ if eq $hw.display_scale 2.0 }}
+font-size = 12               # Retina MacBook
+{{ else if eq $hw.display_scale 1.5 }}
+font-size = 11               # Surface Pro
+{{ else }}
+font-size = 14               # External 1440p/4K
+{{ end }}
+```
+
+On the MacBook: 12pt. On the Surface: 11pt. On the NUC: 14pt. One template.
+
+## Example: Platform × Preset
+
+Combine `.chezmoi.os` with the preset:
+
+```go
+{{- $hw := index .hardware .machine }}
+
+{{ if and (eq .chezmoi.os "darwin") (eq $hw.wm "aerospace") }}
+# macOS + AeroSpace specifics
+{{ else if and (eq .chezmoi.os "linux") (eq $hw.wm "niri") }}
+# Linux + Niri specifics
+{{ end }}
+```
+
+## Listing Known Presets
+
+```sh
+chezmoi execute-template '{{- range $name, $_ := .hardware }}{{ $name }}{{ "\n" }}{{ end }}'
+# macbook-t2
+# surface-pro
+# geekom-a9
+# my-nuc
+```
+
+## Changing Presets on an Existing Host
+
+If you reassign a host to a different preset:
+
+```sh
+# Edit ~/.config/chezmoi/chezmoi.toml
+# machine = "my-nuc" (was "surface-pro")
+
+dot apply --dry-run   # preview changes
+dot apply             # apply
+```
+
+Chezmoi re-renders every template with the new preset data. No reboot needed.
+
+## Troubleshooting
+
+### "Machine preset 'foo' not found"
+
+The `machine` value in `~/.config/chezmoi/chezmoi.toml` doesn't match any key under `[hardware.*]` in `.chezmoidata/hardware.toml`. Check spelling.
+
+### Templates Silently Use Defaults
+
+Make sure you're using `{{- $hw := index .hardware .machine }}` at the top of templates. If `machine` is empty, `index` returns `nil` — reference with `{{- with $hw }}...{{- end }}` guards.
+
+### Feature Flag Not Taking Effect
+
+Verify the merge order:
+
+```sh
+chezmoi execute-template '{{- $hw := index .hardware .machine -}}{{- $f := mergeOverwrite .features $hw.features -}}{{ $f | toToml }}'
+```
+
+Per-preset features must override global defaults. If the output doesn't reflect that, check template syntax.
+
+## Summary
+
+Profiles let one source tree produce correctly-configured output on every host you own. The machinery:
+
+1. `.chezmoidata/hardware.toml` defines presets (declarative)
+2. `~/.config/chezmoi/chezmoi.toml` selects a preset per host (per-host override)
+3. `.tmpl` files read `.hardware` + `.machine` (template-time)
+
+## Next
+
+- [Concept: Fleet Architecture](../01-concepts/04-fleet.md)
+- [Reference: Templates](../03-reference/04-templates.md)
+- [Reference: Feature Flags](../03-reference/05-feature-flags.md)