@sebastienrousseau/dotfiles 0.2.519 → 0.2.521

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

@@ -1,197 +0,0 @@
----
-render_with_liquid: false
----
-
-# 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/main/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** | Codex, Copilot CLI, Antigravity CLI (`agy`) via native installer; Claude Code via Anthropic's native installer |
-| **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

@@ -1,216 +0,0 @@
----
-render_with_liquid: false
----
-
-# 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
-----                        ------     ----
-monterey-dark               system     /System/Library/Desktop Pictures/.thumbnails/Monterey Dark.heic
-monterey-light              system     /System/Library/Desktop Pictures/.thumbnails/Monterey Light.heic
-tahoe-dark                  system     /System/Library/Desktop Pictures/.thumbnails/Tahoe Dark.heic
-tahoe-light                 system     /System/Library/Desktop Pictures/.thumbnails/Tahoe Light.heic
-sonoma-dark                 system     /System/Library/Desktop Pictures/.thumbnails/Sonoma Dark.heic
-...
-Total: 152 wallpapers
-```
-
-Switch to any system wallpaper:
-
-```sh
-dot theme monterey-dark
-```
-
-The engine extracts Monterey 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

@@ -1,244 +0,0 @@
----
-render_with_liquid: false
----
-{% raw %}
-
-# 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 = "monterey-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)
-{% endraw %}