@sebastienrousseau/dotfiles 0.2.481 → 0.2.500

package/docs/manual/03-reference/03-environment.md

@@ -0,0 +1,120 @@
+# Reference: Environment Variables
+
+All environment variables that affect `.dotfiles` behaviour.
+
+## User-Settable
+
+Variables you can set in your shell to change behaviour.
+
+| Variable | Default | Effect |
+|:---|:---|:---|
+| `DOTFILES_VERBOSE` | unset | Verbose output from `dot` commands |
+| `DOTFILES_NONINTERACTIVE` | unset | Skip interactive prompts (for CI) |
+| `DOTFILES_SILENT` | unset | Suppress non-error output |
+| `DOTFILES_DEBUG` | unset | Print shell-init timing to stderr |
+| `DOTFILES_SOURCE_DIR` | `~/.dotfiles` | Override the source directory |
+| `DOTFILES_WALLPAPER_DIR` | `~/Pictures/Wallpapers` | Custom wallpaper directory |
+| `DOTFILES_CACHE_DIR` | `~/.cache/dotfiles` | Override cache location |
+| `DOTFILES_STATE_DIR` | `~/.local/state/dotfiles` | Override state directory |
+| `DOTFILES_TUNING` | `0` | Enable OS tuning (`dot tune`) |
+| `EDITOR` | `nvim` | Editor used by `dot edit` and `sops` |
+| `PAGER` | `less` | Pager used by `dot manual text` |
+
+## Auto-Populated
+
+Variables the dotfiles set in your shell for tool consumption.
+
+| Variable | Value | Source |
+|:---|:---|:---|
+| `XDG_CONFIG_HOME` | `~/.config` | `dot_zshenv` / `dot_config/fish/conf.d/env.fish.tmpl` |
+| `XDG_CACHE_HOME` | `~/.cache` | ditto |
+| `XDG_DATA_HOME` | `~/.local/share` | ditto |
+| `XDG_STATE_HOME` | `~/.local/state` | ditto |
+| `PATH` | managed order | `dot_config/shell/00-core-paths.sh.tmpl` |
+| `BUN_INSTALL` | `~/.bun` | `env.fish.tmpl` |
+| `PIPX_HOME` | `~/.local/share/pipx` | ditto |
+| `PIPX_BIN_DIR` | `~/.local/bin` | ditto |
+| `BUILDS_TMPDIR` | `/tmp/builds` | `dot_zshenv` (created on shell init) |
+| `CARGO_TARGET_DIR` | (from `~/.cargo/config.toml`) | `target-dir = "/tmp/builds/cargo"` |
+| `GOCACHE` | `/tmp/builds/go-cache` | `mise [env]` |
+| `GOTMPDIR` | `/tmp/builds/go-tmp` | `mise [env]` |
+| `PIP_CACHE_DIR` | `/tmp/builds/pip-cache` | `mise [env]` |
+| `UV_CACHE_DIR` | `/tmp/builds/uv-cache` | `mise [env]` |
+| `ZIG_LOCAL_CACHE_DIR` | `/tmp/builds/zig-cache` | `mise [env]` |
+| `ZIG_GLOBAL_CACHE_DIR` | `/tmp/builds/zig-global-cache` | `mise [env]` |
+| `HOMEBREW_PREFIX` | `/opt/homebrew` or `/usr/local` | `dot_zshenv` (macOS) |
+| `MANPATH` | homebrew-adjusted | ditto |
+| `MISE_EXPERIMENTAL` | `1` | `~/.config/mise/config.toml` |
+| `GITHUB_TOKEN` | from `gh auth token` | `~/.config/mise/config.toml` |
+
+## Read by Tools
+
+Variables set by upstream tools and respected by `.dotfiles`.
+
+| Variable | Used for |
+|:---|:---|
+| `SHELL` | Detect default shell |
+| `TERM` | Terminal capabilities (e.g. `xterm-256color`) |
+| `COLORTERM` | True-color detection (`truecolor`) |
+| `LANG` / `LC_ALL` | Locale (must be UTF-8) |
+| `HOME` | User home directory |
+| `USER` | Username |
+| `SSH_AUTH_SOCK` | ssh-agent socket |
+| `GPG_TTY` | GPG pinentry TTY |
+
+## CI-Specific
+
+Variables relevant in GitHub Actions.
+
+| Variable | Purpose |
+|:---|:---|
+| `CI` | Set to `true` in CI; disables prompts |
+| `GITHUB_ACTIONS` | GHA-specific; enables step summary output |
+| `CHEZMOI_VERSION` | Pinned chezmoi version for CI |
+| `COVERAGE_THRESHOLD` | Test coverage threshold (100 in enforced CI) |
+| `DOTFILES_TEST_MODE` | Skip network-dependent tests |
+
+## Secret-Related
+
+| Variable | Purpose |
+|:---|:---|
+| `SOPS_AGE_KEY_FILE` | Override `~/.config/age/keys.txt` path |
+| `SOPS_AGE_RECIPIENTS` | Override recipients for new encryption |
+| `CHEZMOI_AGE_IDENTITY` | Override age identity for chezmoi decrypt |
+
+> Warning: never set these to values stored in plaintext config. Use a password manager or ephemeral injection.
+
+## Startup Order
+
+Shell-loaded variables follow this precedence (later wins):
+
+1. System defaults (`/etc/environment`, `/etc/profile`)
+2. Homebrew shellenv (macOS)
+3. `~/.zshenv` (earliest user-level file; sets XDG + PATH bootstrap)
+4. `~/.zprofile` or `~/.config/fish/conf.d/*.fish`
+5. `~/.zshrc` or `~/.config/fish/config.fish`
+6. `mise activate` — injects tool-specific env
+7. Per-project `.envrc` via direnv (opt-in)
+
+To debug: `DOTFILES_DEBUG=1 zsh -i -c exit` prints timing for each stage.
+
+## Unsetting
+
+To clean up environment pollution:
+
+```sh
+# Show current dotfiles-set vars
+env | grep -E '^(DOTFILES_|XDG_|BUILDS_)'
+
+# Unset one
+unset DOTFILES_DEBUG
+
+# Reset to defaults (restart shell)
+exec $SHELL -l
+```
+
+## See Also
+
+- [Configuration Files](02-config-files.md)
+- [Feature Flags](05-feature-flags.md)
+- [First Install](../02-tutorials/01-first-install.md)

package/docs/manual/03-reference/04-templates.md

@@ -0,0 +1,184 @@
+# Reference: Template Variables
+
+Every variable available to chezmoi templates (`.tmpl` files).
+
+## From `.chezmoidata.toml`
+
+Flat top-level keys:
+
+| Variable | Type | Example |
+|:---|:---|:---|
+| `.dotfiles_version` | string | `"0.2.500"` |
+| `.theme` | string | `"tahoe-dark"` |
+| `.machine` | string | `"macbook-t2"` |
+| `.profile` | string | `"laptop"` |
+| `.default_shell` | string | `"fish"` |
+| `.terminal_font_family` | string | `"JetBrainsMono Nerd Font"` |
+| `.terminal_font_size` | int | `12` |
+| `.name` | string | `"Your Name"` |
+| `.email` | string | `"you@example.com"` |
+
+## From `.chezmoidata/themes.toml`
+
+```go
+{{- $t := index .themes .theme }}
+{{ $t.mode }}              // "dark" or "light"
+{{ $t.family }}            // "tahoe"
+{{ $t.macos_accent }}      // 4 (integer)
+{{ $t.term.bg }}           // "#121430"
+{{ $t.term.fg }}           // "#d4d8ec"
+{{ $t.term.c0 }} .. {{ $t.term.c15 }}   // ANSI 0-15
+{{ $t.ui.accent }}         // "#3951b1"
+{{ $t.ui.accent_text }}    // "#ffffff"
+{{ $t.ui.panel }}
+{{ $t.ui.border }}
+{{ $t.app.nvim }}          // "catppuccin"
+{{ $t.app.starship_palette }}
+```
+
+## From `.chezmoidata/hardware.toml`
+
+```go
+{{- $hw := index .hardware .machine }}
+{{ $hw.display_scale }}    // 2.0
+{{ $hw.kbd_layout }}       // "qwerty"
+{{ $hw.modifier_mode }}    // "left-cmd-control"
+{{ $hw.perf_profile }}     // "laptop"
+{{ $hw.wm }}               // "aerospace"
+{{ $hw.features.touchid }} // bool
+```
+
+## From Feature Flags
+
+```go
+{{- $f := mergeOverwrite .features $hw.features }}
+{{ if $f.dms }}
+# Dank Material Shell-specific config
+{{ end }}
+
+{{ if $f.niri }}
+# Niri WM config
+{{ end }}
+```
+
+## Built-in Chezmoi Variables
+
+```go
+{{ .chezmoi.os }}                // "darwin" | "linux" | "windows"
+{{ .chezmoi.arch }}              // "amd64" | "arm64"
+{{ .chezmoi.kernel }}            // "Darwin" | "Linux"
+{{ .chezmoi.kernel.ostype }}     // "darwin24" etc
+{{ .chezmoi.hostname }}          // host machine hostname
+{{ .chezmoi.username }}          // current user
+{{ .chezmoi.homeDir }}           // $HOME
+{{ .chezmoi.sourceDir }}         // ~/.dotfiles
+{{ .chezmoi.workingTree }}       // git working tree root
+{{ .chezmoi.executable }}        // chezmoi binary path
+{{ .chezmoi.osRelease }}         // Linux /etc/os-release data
+```
+
+## Built-in Chezmoi Functions
+
+```go
+{{ exec "command" | trim }}
+{{ output "hostname" }}
+{{ include "path/to/file" }}
+{{ decrypt "path/to/file.age" }}
+{{ sopsDecrypt "path/to/file.sops.yaml" | fromYaml }}
+{{ joinPath "a" "b" }}
+{{ stat "/path" }}
+{{ ioreg ".." ".." }}             // macOS only
+{{ lookPath "command" }}           // returns path or empty
+```
+
+## Helper Templates (in `.chezmoitemplates/`)
+
+Reusable partials included via:
+
+```go
+{{ template "paths/00-default.paths.sh" . }}
+{{ template "aliases/cd.aliases.sh" . }}
+{{ template "functions/cdls.sh" . }}
+```
+
+Available partials:
+
+- `paths/00-default.paths.sh` — canonical PATH construction
+- `paths/05-pipx.paths.sh` — pipx + ~/.local/bin
+- `paths/99-custom.paths.sh` — user-appended paths
+- `aliases/*.aliases.sh` — per-domain alias sets
+- `functions/*.sh` — reusable shell functions
+
+## Example: Using Theme in Ghostty Config
+
+```go
+{{- /* dot_config/ghostty/config.tmpl */ -}}
+{{- $t := index .themes .theme -}}
+
+font-family = "{{ .terminal_font_family }}"
+font-size = {{ .terminal_font_size }}
+
+background = {{ $t.term.bg }}
+foreground = {{ $t.term.fg }}
+cursor-color = {{ $t.term.cursor }}
+
+palette = 0={{ $t.term.c0 }}
+palette = 1={{ $t.term.c1 }}
+palette = 2={{ $t.term.c2 }}
+# ... through 15
+
+{{- if eq .chezmoi.os "darwin" }}
+macos-titlebar-style = transparent
+{{- end }}
+```
+
+## Example: Platform × Preset
+
+```go
+{{- $hw := index .hardware .machine -}}
+
+{{- if and (eq .chezmoi.os "darwin") (eq $hw.wm "aerospace") }}
+# macOS AeroSpace config
+include = ["aerospace-macos.toml"]
+{{- else if and (eq .chezmoi.os "linux") (eq $hw.wm "niri") }}
+# Linux Niri config
+include = ["niri.kdl"]
+{{- end }}
+
+# DPI-aware sizing
+font-size = {{ mul 8 $hw.display_scale | int }}
+```
+
+## Template Testing
+
+Render a template without applying:
+
+```sh
+chezmoi execute-template < dot_config/ghostty/config.tmpl
+```
+
+Or test an expression:
+
+```sh
+chezmoi execute-template '{{ .chezmoi.os }}'
+# darwin
+
+chezmoi execute-template '{{- $t := index .themes .theme -}}{{ $t.term.bg }}'
+# #121430
+```
+
+## Validation in CI
+
+Every push to master runs:
+
+```sh
+chezmoi apply --dry-run
+```
+
+If any template fails to render, the build breaks before merge.
+
+## See Also
+
+- [Chezmoi template reference](https://www.chezmoi.io/reference/templates/)
+- [Configuration Files](02-config-files.md)
+- [Create a Profile tutorial](../02-tutorials/03-create-profile.md)

package/docs/manual/03-reference/05-feature-flags.md

@@ -0,0 +1,118 @@
+# Reference: Feature Flags
+
+Feature flags toggle optional subsystems. Set in `.chezmoidata.toml`, override per-preset in `.chezmoidata/hardware.toml`.
+
+## Global Flags (`.chezmoidata.toml`)
+
+```toml
+[features]
+dms = false                # Dank Material Shell (Niri desktop)
+linux_desktop = false      # Linux-specific desktop configs
+niri = false               # Niri window manager
+waybar = false             # Waybar status bar
+```
+
+## Per-Preset Overrides (`.chezmoidata/hardware.toml`)
+
+```toml
+[hardware.surface-pro.features]
+niri = true
+waybar = true
+dms = true                 # overrides .chezmoidata.toml default
+```
+
+The effective value is `mergeOverwrite` of global + preset features.
+
+## Flag Catalogue
+
+### `dms` — Dank Material Shell
+
+When `true`:
+- Configures DMS IPC for theme sync
+- Enables Quickshell templates
+- Sets up per-monitor wallpaper via `dms ipc wallpaper`
+
+Requires: Niri + Quickshell + DMS installed.
+
+### `linux_desktop` — Linux Desktop Configs
+
+When `true`:
+- Enables GTK 3/4 theme generation from `themes.toml`
+- Configures `gsettings color-scheme` behaviour
+- Generates desktop file entries for installed tools
+
+No effect on macOS.
+
+### `niri` — Niri Window Manager
+
+When `true`:
+- Generates `~/.config/niri/config.kdl`
+- Enables Niri keybindings from `keybinds.toml`
+- Configures workspace rules per preset
+
+Requires: Niri installed.
+
+### `waybar` — Waybar Status Bar
+
+When `true`:
+- Generates `~/.config/waybar/config.jsonc` + `style.css`
+- Hooks into theme switching via `dot-theme-sync`
+
+Requires: Waybar installed.
+
+## Using a Flag in a Template
+
+```go
+{{- $hw := index .hardware .machine }}
+{{- $f := mergeOverwrite .features $hw.features }}
+
+{{ if $f.niri }}
+# Niri-specific config
+{{ end }}
+```
+
+## Checking Active Flags
+
+```sh
+chezmoi execute-template '{{- $hw := index .hardware .machine -}}{{- $f := mergeOverwrite .features $hw.features -}}{{ $f | toToml }}'
+```
+
+## Adding a New Flag
+
+1. Add to `.chezmoidata.toml`:
+
+   ```toml
+   [features]
+   my_new_flag = false
+   ```
+
+2. (Optional) Set per preset:
+
+   ```toml
+   [hardware.macbook-t2.features]
+   my_new_flag = true
+   ```
+
+3. Use in templates:
+
+   ```go
+   {{ if $f.my_new_flag }}
+   # conditional config
+   {{ end }}
+   ```
+
+4. Document here with the flag's purpose and requirements
+
+## Flag Deprecation
+
+Flags can be deprecated without breaking existing hosts. The deprecation process:
+
+1. Mark the flag as deprecated in this document
+2. Leave the flag evaluation in place for one release
+3. In the subsequent release, remove the template branches and the flag definition
+4. Users who had the flag set will see it ignored — no errors
+
+## See Also
+
+- [Configuration Files](02-config-files.md)
+- [Create a Profile](../02-tutorials/03-create-profile.md)

package/docs/manual/04-cookbook/01-recipes.md

@@ -0,0 +1,281 @@
+# Cookbook: Recipes
+
+Thirty short recipes for common tasks.
+
+## Installation & Update
+
+### 1. Install on a fresh machine
+
+```sh
+bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh)"
+```
+
+### 2. Update everything
+
+```sh
+dot upgrade
+```
+
+### 3. Update dotfiles only (no tools)
+
+```sh
+dot update
+```
+
+### 4. Preview what would change
+
+```sh
+dot apply --dry-run
+```
+
+## Themes
+
+### 5. Switch to a specific theme
+
+```sh
+dot theme tahoe-dark
+```
+
+### 6. Toggle between dark and light
+
+```sh
+dot theme toggle
+```
+
+### 7. Open the interactive theme picker
+
+```sh
+dot theme
+```
+
+### 8. List paired wallpaper themes
+
+```sh
+dot theme list
+```
+
+### 9. Add a new wallpaper-driven theme
+
+```sh
+cp my-wallpaper.jpg ~/Pictures/Wallpapers/myname-dark.jpg
+cp my-wallpaper-light.jpg ~/Pictures/Wallpapers/myname-light.jpg
+bash scripts/theme/merge-wallpaper.sh myname
+dot theme rebuild
+dot theme myname-dark
+```
+
+### 10. Regenerate all themes from scratch
+
+```sh
+dot theme rebuild --force
+```
+
+## Configuration
+
+### 11. Edit the source directory
+
+```sh
+dot edit
+```
+
+### 12. Add a new config file to chezmoi
+
+```sh
+dot add ~/.some-config-file
+```
+
+### 13. Remove a managed file
+
+```sh
+dot remove ~/.some-config-file
+```
+
+### 14. Show configuration drift
+
+```sh
+dot status
+```
+
+### 15. Show diff against source
+
+```sh
+dot diff
+```
+
+## Secrets
+
+### 16. Encrypt a new secret file
+
+```sh
+chezmoi add --encrypt ~/some-secret.txt
+```
+
+### 17. Edit an encrypted file
+
+```sh
+sops dot_config/credentials.sops.yaml
+# or
+chezmoi edit ~/some-secret.txt.age
+```
+
+### 18. Rotate your Age key
+
+```sh
+age-keygen -o ~/.config/age/keys.txt.new
+# Update .sops.yaml with new public key
+# Then:
+find . -name '*.sops.yaml' -exec sops updatekeys {} \;
+git commit -sS -am "chore(secrets): rotate age key"
+```
+
+### 19. Check for accidental secret leaks
+
+```sh
+dot verify --security
+```
+
+## Diagnostics
+
+### 20. Quick health check
+
+```sh
+dot doctor
+```
+
+### 21. Auto-fix common issues
+
+```sh
+dot heal
+```
+
+### 22. Check startup performance
+
+```sh
+dot benchmark
+```
+
+### 23. See the health score
+
+```sh
+dot score
+```
+
+### 24. Recent metrics
+
+```sh
+dot metrics
+```
+
+## Fleet
+
+### 25. Attest across all fleet hosts
+
+```sh
+dot fleet attest
+```
+
+### 26. Sync dotfiles to every fleet host
+
+```sh
+dot fleet sync
+```
+
+### 27. Diff config across hosts
+
+```sh
+dot fleet diff
+```
+
+## AI & Agents
+
+### 28. Show installed AI tools
+
+```sh
+dot ai
+```
+
+### 29. Switch agent profile
+
+```sh
+dot mode architect   # or hardener, refactor
+```
+
+### 30. Verify MCP policy
+
+```sh
+dot mcp --strict
+```
+
+## Recovery
+
+### 31. Rollback the last apply
+
+```sh
+dot rollback
+```
+
+### 32. Create an offline bundle
+
+```sh
+dot bundle
+```
+
+### 33. Restore from a bundle
+
+```sh
+dot bundle restore ~/Downloads/dotfiles-bundle-*.tar.zst
+```
+
+## Development
+
+### 34. Run a test locally
+
+```sh
+bash tests/unit/theme/test_themes_toml.sh
+```
+
+### 35. Run all tests
+
+```sh
+./tests/framework/test_runner.sh
+```
+
+### 36. Lint shell scripts
+
+```sh
+dot lint
+```
+
+### 37. Simulate chaos to test self-healing
+
+```sh
+dot chaos symlink   # in an ephemeral container only
+dot heal
+dot doctor
+```
+
+## Manual
+
+### 38. Open the manual in a browser
+
+```sh
+dot manual
+```
+
+### 39. Download the PDF
+
+```sh
+dot manual pdf
+```
+
+### 40. Read the manual in a terminal
+
+```sh
+dot manual text | less
+```
+
+## See Also
+
+- [Troubleshooting](02-troubleshooting.md)
+- [FAQ](03-faq.md)
+- [CLI Reference](../03-reference/01-dot-cli.md)