@sebastienrousseau/dotfiles 0.2.499 → 0.2.500

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)

package/docs/manual/02-tutorials/04-encrypt-secret.md

@@ -0,0 +1,275 @@
+# Tutorial: Encrypt a Secret
+
+How to store an API key (or any secret) encrypted in the repository using Age and SOPS — decrypted automatically on `dot apply`.
+
+## The Threat Model
+
+Secrets in plaintext config files are:
+
+- Committed to Git history (permanent record)
+- Visible to every process on the machine
+- Included in backup archives
+
+Secrets encrypted with Age:
+
+- Cipher text committed to Git is useless without the private key
+- Private key (`~/.config/age/keys.txt`) never leaves the user's machine
+- Per-machine policy: only authorized hosts hold keys for their share of secrets
+
+## Step 1: Generate an Age Key (First Time Only)
+
+```sh
+age-keygen -o ~/.config/age/keys.txt
+chmod 600 ~/.config/age/keys.txt
+```
+
+The public key is embedded in the file:
+
+```sh
+cat ~/.config/age/keys.txt
+# created: 2026-04-16T09:00:00Z
+# public key: age1qy90l...xyz
+AGE-SECRET-KEY-1A...
+```
+
+Copy the public key — you'll reference it when encrypting.
+
+## Step 2: Choose Encryption Method
+
+Two approaches are supported:
+
+| Method | Best For | Filename |
+|:---|:---|:---|
+| **Chezmoi encrypt** | Individual files (API tokens, config snippets) | `dot_config/token.age` |
+| **SOPS** | YAML/JSON with multiple secrets, selective field encryption | `dot_config/creds.sops.yaml` |
+
+## Step 3A: Chezmoi-Encrypted File
+
+Create an unencrypted source file:
+
+```sh
+mkdir -p ~/tmp
+echo "sk_live_abc123" > ~/tmp/stripe-key.txt
+```
+
+Import it as encrypted:
+
+```sh
+chezmoi add --encrypt ~/tmp/stripe-key.txt
+```
+
+This:
+
+1. Reads `~/tmp/stripe-key.txt`
+2. Encrypts with your Age public key
+3. Stores encrypted content at `~/.dotfiles/dot_tmp/stripe-key.txt.age`
+4. Template reads encrypted content at apply time and decrypts to target
+
+Delete the plaintext source:
+
+```sh
+rm ~/tmp/stripe-key.txt
+```
+
+On `dot apply`, chezmoi decrypts and writes to `~/tmp/stripe-key.txt`. If someone lacks the private key, they see only the encrypted `.age` file in Git.
+
+## Step 3B: SOPS-Encrypted YAML
+
+SOPS encrypts **values** in YAML/JSON while preserving the structure. Useful when you want:
+
+- Multiple secrets in one file
+- Encryption of only sensitive fields (leaving metadata readable)
+- Multi-recipient (e.g. the work laptop AND the backup laptop can decrypt)
+
+Configure SOPS once:
+
+```yaml
+# .sops.yaml (at repo root)
+creation_rules:
+  - path_regex: \.sops\.yaml$
+    age: age1qy90l...xyz
+```
+
+Create a secrets file:
+
+```yaml
+# dot_config/credentials.sops.yaml
+database:
+  host: db.prod.example.com
+  user: app
+  password: supersecret
+api_keys:
+  stripe: sk_live_abc
+  sendgrid: SG.xyz
+```
+
+Encrypt it:
+
+```sh
+sops --encrypt --in-place dot_config/credentials.sops.yaml
+```
+
+The file now contains ciphertext blobs where plaintext values were:
+
+```yaml
+database:
+    host: ENC[AES256_GCM,data:...]
+    user: ENC[AES256_GCM,data:...]
+    password: ENC[AES256_GCM,data:...]
+api_keys:
+    stripe: ENC[AES256_GCM,data:...]
+    sendgrid: ENC[AES256_GCM,data:...]
+sops:
+    age:
+        - recipient: age1qy90l...xyz
+          enc: |
+            -----BEGIN AGE ENCRYPTED FILE-----
+            ...
+```
+
+To edit the encrypted file:
+
+```sh
+sops dot_config/credentials.sops.yaml
+# Opens in $EDITOR with decrypted content; re-encrypts on save
+```
+
+## Step 4: Reference the Secret in a Template
+
+Chezmoi has a built-in `decrypt` helper:
+
+```go
+# dot_bashrc.tmpl
+export STRIPE_KEY="{{ include "dot_tmp/stripe-key.txt.age" | decrypt | trim }}"
+```
+
+For SOPS:
+
+```go
+# Use the sopsDecrypt template function
+{{- $creds := dict -}}
+{{- $creds = sopsDecrypt "dot_config/credentials.sops.yaml" | fromYaml }}
+export DB_PASSWORD="{{ $creds.database.password }}"
+```
+
+## Step 5: Commit and Verify
+
+```sh
+cd ~/.dotfiles
+git add .sops.yaml dot_config/credentials.sops.yaml dot_tmp/stripe-key.txt.age
+git commit -sS -m "feat(secrets): add stripe and database credentials"
+git push
+```
+
+Verify the commit doesn't leak secrets:
+
+```sh
+git log -p HEAD~1..HEAD | grep -v ENC | grep -iE 'password|secret|key' || echo "Clean"
+```
+
+On the next machine:
+
+```sh
+dot update
+# Chezmoi decrypts using that machine's Age key
+# If decryption fails, the template errors with a clear message
+```
+
+## Step 6: Multi-Recipient (Fleet)
+
+To allow multiple hosts to decrypt the same secret, add more recipients:
+
+```yaml
+# .sops.yaml
+creation_rules:
+  - path_regex: \.sops\.yaml$
+    age: >-
+      age1qy90l...xyz,
+      age1z2x33...abc,
+      age1mm0kk...def
+```
+
+Re-encrypt the affected files:
+
+```sh
+sops updatekeys dot_config/credentials.sops.yaml
+```
+
+Now any host with one of those three private keys can decrypt. Hosts without any matching key see the encrypted file but cannot read it.
+
+## Step 7: Rotate a Compromised Key
+
+```sh
+# 1. Generate a new Age key on the affected host
+age-keygen -o ~/.config/age/keys.txt.new
+mv ~/.config/age/keys.txt.new ~/.config/age/keys.txt
+
+# 2. Update .sops.yaml with the new public key
+
+# 3. Re-encrypt all SOPS files with the new recipient list
+find . -name '*.sops.yaml' -exec sops updatekeys {} \;
+
+# 4. Commit and push
+git add .sops.yaml dot_config/*.sops.yaml
+git commit -sS -m "chore(secrets): rotate Age key"
+
+# 5. On other fleet hosts
+dot update
+```
+
+Old key still works for existing ciphertext, but new secrets use the new key. To force deprecation, delete the old key from `.sops.yaml` and `sops updatekeys` all files.
+
+## Verifying No Plaintext Leaks
+
+CI runs three secret scanners (`gitleaks`, `detect-secrets`, `trufflehog`) on every commit. You can run them locally:
+
+```sh
+gitleaks detect --redact --source .
+detect-secrets scan --update .secrets.baseline
+trufflehog git file://. --only-verified
+```
+
+If any scanner finds a potential leak, the commit is blocked.
+
+## Operational Rules
+
+1. **Never commit plaintext secrets** — use chezmoi encrypt or SOPS
+2. **Never commit `~/.config/age/keys.txt`** — it's gitignored; double-check before pushing
+3. **Age keys are per-host** — don't copy them via Git; use secure channels (1Password, Bitwarden, physical USB)
+4. **Rotate on team membership changes** — when someone leaves, update recipients and rotate all shared secrets
+5. **Audit with `dot verify --security`** — runs gitleaks + signature + policy hash checks
+
+## Troubleshooting
+
+### "Could not decrypt: no age key found"
+
+`~/.config/age/keys.txt` is missing or unreadable:
+
+```sh
+chmod 600 ~/.config/age/keys.txt
+ls -la ~/.config/age/keys.txt
+# -rw------- 1 user user 189 Apr 16 09:00 keys.txt
+```
+
+### "sops: file encrypted with outdated recipients"
+
+A secret file has an old recipient list. Fix:
+
+```sh
+sops updatekeys path/to/file.sops.yaml
+```
+
+### Secrets Not Applying After Apply
+
+Check that `dot_tmp/stripe-key.txt.age` is committed. Run:
+
+```sh
+chezmoi apply --verbose dot_tmp/stripe-key.txt
+# Will show decrypt attempts and errors
+```
+
+## Next
+
+- [Concept: Trust Model](../01-concepts/02-trust-model.md) — the security architecture
+- [Reference: Secret operations](../03-reference/01-dot-cli.md#secrets)
+- [Security: Secret management](../../security/SECRETS.md)