@sebastienrousseau/dotfiles 0.2.500 → 0.2.501

package/docs/adr/ADR-001-ci-cd-pipeline.md

@@ -1,3 +1,8 @@
+---
+render_with_liquid: false
+---
+{% raw %}
+
 # ADR-001: Multi-stage CI/CD Pipeline Design
 
 **Status**: Accepted
@@ -7,6 +12,7 @@
 ## Context
 
 The dotfiles repository requires a CI/CD pipeline that:
+
 - Validates changes across multiple platforms (Linux, macOS)
 - Runs security scans to detect secrets and vulnerabilities
 - Tests shell scripts, Lua configurations, and Nix expressions
@@ -14,6 +20,7 @@ The dotfiles repository requires a CI/CD pipeline that:
 - Minimizes GitHub Actions costs (runner minutes)
 
 Traditional approaches run all checks on every commit, leading to:
+
 - Wasted compute on unrelated changes (e.g., running Lua linting when only docs change)
 - High costs from macOS runners ($0.08/min vs $0.008/min for Linux)
 - Long feedback times from sequential job execution
@@ -23,27 +30,33 @@ Traditional approaches run all checks on every commit, leading to:
 Implement a **5-stage progressive CI pipeline** with path-based filtering:
 
 ### Stage 1: Change Detection
+
 Use `dorny/paths-filter` to detect which file categories changed:
+
 - `shell`: *.sh, scripts/**, install/**
 - `lua`: dot_config/nvim/**, *.lua
 - `nix`: nix/**, *.nix
 - `config`: dot_*/**, .chezmoitemplates/**
 
 ### Stage 2: Lint (Parallel, Conditional)
+
 - **lint-shell**: Only runs if shell files changed
 - **lint-lua**: Only runs if Lua files changed
 - Run in parallel to minimize wall-clock time
 
 ### Stage 3: Security (Always on PRs)
+
 - **secrets-scan**: Gitleaks on every PR (critical)
 - **link-check**: Only on schedule (expensive)
 
 ### Stage 4: Test (Conditional Matrix)
+
 - Linux-only for PRs (cheapest)
 - Full matrix (Linux + macOS) on schedule/manual trigger
 - Docker container tests for installation validation
 
 ### Stage 5: Quality (Schedule/Manual Only)
+
 - Idempotency verification
 - Performance benchmarks
 - Nix flake checks
@@ -58,17 +71,20 @@ Use `dorny/paths-filter` to detect which file categories changed:
 ## Consequences
 
 ### Positive
+
 - ~50% reduction in GitHub Actions minutes
 - Fast feedback for most changes (1-3 minutes)
 - Comprehensive testing still available via schedule/manual
 - Clear separation of concerns between stages
 
 ### Negative
+
 - Complexity in workflow configuration
 - Some bugs might only surface in scheduled runs
 - Path filter maintenance required as repo structure evolves
 
 ### Neutral
+
 - Developers can trigger full CI manually with `workflow_dispatch`
 - Breaking changes to CI require testing across all stages
 
@@ -99,3 +115,4 @@ jobs:
 
 - [GitHub Actions Path Filtering](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore)
 - [dorny/paths-filter](https://github.com/dorny/paths-filter)
+{% endraw %}

package/docs/adr/ADR-002-shell-performance.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # ADR-002: Shell Performance Optimization Strategy
 
 **Status**: Accepted
@@ -12,6 +16,7 @@ configurations (completions, prompts, plugins), startup can easily exceed 1-2
 seconds.
 
 Goals:
+
 - Target startup time: <500ms for interactive shells
 - Maintain full functionality (completions, syntax highlighting, git info)
 - Support both zsh and bash
@@ -84,6 +89,7 @@ zinit light zsh-users/zsh-autosuggestions
 ### Monitoring
 
 Benchmark script to track startup time:
+
 ```bash
 hyperfine --warmup 3 --runs 10 "zsh -i -c exit"
 ```
@@ -93,17 +99,20 @@ CI enforces 500ms threshold with warnings.
 ## Consequences
 
 ### Positive
+
 - Consistent <500ms startup across platforms
 - Full functionality preserved
 - Easy to add new tools without performance regression
 - Clear patterns for contributors to follow
 
 ### Negative
+
 - First invocation of lazy-loaded commands is slower
 - Cache invalidation bugs can cause stale behavior
 - Complexity in understanding load order
 
 ### Neutral
+
 - Profiling required when adding new plugins
 - Trade-off between convenience and performance explicit
 

package/docs/adr/ADR-003-security-first.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # ADR-003: Security-First Approach
 
 **Status**: Accepted
@@ -7,6 +11,7 @@
 ## Context
 
 Dotfiles repositories present unique security challenges:
+
 - They configure system behavior and permissions
 - They may contain or reference secrets (API keys, tokens)
 - They execute scripts with user privileges
@@ -21,6 +26,7 @@ Implement a **defense-in-depth security model** with multiple layers:
 ### Layer 1: Secrets Protection
 
 **Never commit secrets:**
+
 ```bash
 # .gitleaks.toml - block common secret patterns
 [[rules]]
@@ -29,6 +35,7 @@ regex = '''(?i)(api[_-]?key|apikey)\s*[:=]\s*['"]?([a-zA-Z0-9]{20,})'''
 ```
 
 **Encrypted secrets with age:**
+
 ```bash
 # Secrets stored encrypted, decrypted at apply time
 chezmoi.encryption = "age"
@@ -36,6 +43,7 @@ chezmoi.age.identity = "~/.config/chezmoi/key.txt"
 ```
 
 **CI enforcement:**
+
 - Gitleaks runs on every PR
 - TruffleHog for verified secrets detection
 - Block merge if secrets detected
@@ -43,6 +51,7 @@ chezmoi.age.identity = "~/.config/chezmoi/key.txt"
 ### Layer 2: Input Validation
 
 **Path traversal prevention:**
+
 ```bash
 # Validate all user inputs
 if [[ ! "$template_lang" =~ ^[a-zA-Z0-9_-]+$ ]]; then
@@ -51,6 +60,7 @@ fi
 ```
 
 **Safe file operations:**
+
 ```bash
 # Use absolute paths, validate before operations
 local real_path
@@ -63,6 +73,7 @@ fi
 ### Layer 3: Opt-in System Modifications
 
 **Dangerous operations require explicit consent:**
+
 ```bash
 # Security scripts are opt-in
 if [ "${DOTFILES_SECURITY:-0}" != "1" ]; then
@@ -72,6 +83,7 @@ fi
 ```
 
 **Comprehensive logging:**
+
 ```bash
 # All system modifications logged
 log_security_change() {
@@ -82,6 +94,7 @@ log_security_change() {
 ### Layer 4: CI Security Scanning
 
 **Multi-tool approach:**
+
 - **Gitleaks**: Secrets in git history
 - **Shellcheck**: Shell script vulnerabilities
 - **Checkov**: Infrastructure misconfigurations
@@ -89,6 +102,7 @@ log_security_change() {
 - **CodeQL**: Static analysis for Python/JavaScript
 
 **Weekly deep scans:**
+
 ```yaml
 schedule:
   - cron: '0 2 * * 0'  # Weekly security audit
@@ -97,6 +111,7 @@ schedule:
 ### Layer 5: Minimal Privileges
 
 **Scripts request only needed permissions:**
+
 ```bash
 # Don't run as root unless necessary
 if [ "$(id -u)" = "0" ]; then
@@ -110,17 +125,20 @@ sudo sysctl -w net.ipv4.tcp_keepalive_time=60
 ## Consequences
 
 ### Positive
+
 - Secrets never enter git history
 - System modifications are auditable
 - Multiple layers catch different vulnerability types
 - Contributors have clear security patterns to follow
 
 ### Negative
+
 - Additional complexity in scripts
 - Encrypted secrets require key management
 - Some features disabled by default (friction)
 
 ### Neutral
+
 - Security vs convenience trade-offs explicit
 - Regular security audits via scheduled CI
 

package/docs/adr/ADR-004-cli-architecture.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # ADR-004: Chezmoi + Custom CLI Wrapper Architecture
 
 **Status**: Accepted
@@ -7,12 +11,14 @@
 ## Context
 
 Managing dotfiles requires:
+
 - Tracking file changes and applying them consistently
 - Handling platform-specific configurations
 - Supporting encrypted secrets
 - Providing a good developer experience
 
 Options considered:
+
 1. **Bare git repository**: Simple but poor UX, no templating
 2. **GNU Stow**: Symlink-based, limited features
 3. **Chezmoi only**: Powerful but complex CLI
@@ -45,18 +51,21 @@ Use **Chezmoi as the core engine** with a **custom `dot` CLI wrapper** that:
 ### Core Principles
 
 **1. Chezmoi handles complexity:**
+
 - Template rendering with Go text/template
 - Encrypted secrets with age
 - State tracking (what's applied vs source)
 - Cross-platform path handling
 
 **2. dot CLI handles UX:**
+
 - Memorable command names (`dot sync` vs `chezmoi apply`)
 - Domain-specific commands (`dot doctor`, `dot theme`)
 - Integration with external tools (Nix, Docker, Neovim)
 - Consistent help and error messages
 
 **3. Modular command structure:**
+
 ```text
 scripts/dot/
 ├── lib/
@@ -72,6 +81,7 @@ scripts/dot/
 ```
 
 **4. Delegation pattern:**
+
 ```bash
 # Main dispatcher in dot CLI
 dispatch() {
@@ -94,6 +104,7 @@ dispatch() {
 ### Extension Points
 
 Custom commands can:
+
 1. Wrap chezmoi commands with better defaults
 2. Add entirely new functionality (benchmarks, themes)
 3. Integrate with system tools (nix, docker, brew)
@@ -102,6 +113,7 @@ Custom commands can:
 ## Consequences
 
 ### Positive
+
 - Leverage Chezmoi's battle-tested engine
 - User-friendly interface for common tasks
 - Easy to add domain-specific commands
@@ -109,11 +121,13 @@ Custom commands can:
 - Single entry point (`dot`) for all operations
 
 ### Negative
+
 - Two layers to understand (chezmoi + dot)
 - Version coupling between chezmoi and scripts
 - Some chezmoi features not exposed via dot
 
 ### Neutral
+
 - Advanced users can still use chezmoi directly
 - Documentation needed for both layers
 - Upgrade path when chezmoi adds new features

package/docs/adr/ADR-005-chezmoi-choice.md

@@ -1,3 +1,8 @@
+---
+render_with_liquid: false
+---
+{% raw %}
+
 # ADR-005: Chezmoi as Dotfiles Manager
 
 **Status**: Accepted
@@ -7,6 +12,7 @@
 ## Context
 
 Managing dotfiles across multiple machines requires:
+
 - Version control for configuration files
 - Template support for machine-specific values
 - Cross-platform compatibility (macOS, Linux, WSL)
@@ -65,6 +71,7 @@ chezmoi apply
 ## Consequences
 
 ### Positive
+
 - Consistent configuration across all machines
 - Secure secrets management with age encryption
 - Easy to add new machines to the fleet
@@ -72,12 +79,14 @@ chezmoi apply
 - Built-in diff and dry-run for safe updates
 
 ### Negative
+
 - Learning curve for Go templates
 - Additional abstraction layer over raw Git
 - Requires chezmoi binary installation
 - Some features (scripts) require careful ordering
 
 ### Neutral
+
 - Configuration stored in `~/.local/share/chezmoi` by default
 - Custom wrapper CLI (`dot`) provides simpler interface
 - Regular `git` commands still work in source directory
@@ -87,3 +96,4 @@ chezmoi apply
 - [Chezmoi Documentation](https://www.chezmoi.io/)
 - [Chezmoi Quick Start](https://www.chezmoi.io/quick-start/)
 - [Comparison with Other Tools](https://www.chezmoi.io/comparison-table/)
+{% endraw %}

package/docs/adr/ADR-006-shell-selection.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # ADR-006: Zsh as Default Shell
 
 **Status**: Accepted
@@ -7,6 +11,7 @@
 ## Context
 
 Choosing a default shell impacts:
+
 - Developer productivity and workflow
 - Plugin ecosystem and extensibility
 - Cross-platform compatibility
@@ -45,6 +50,7 @@ Use **Zsh** as the default interactive shell with **Zinit** as the plugin manage
 | Antibody | ~300ms | Simple, fast |
 
 Zinit provides:
+
 - **Turbo Mode**: Deferred loading after prompt
 - **Ice Modifiers**: Fine-grained control over plugin loading
 - **Binary Installation**: Install completions and binaries
@@ -84,6 +90,7 @@ zinit light zdharma-continuum/fast-syntax-highlighting
 ## Consequences
 
 ### Positive
+
 - Fast, responsive shell experience
 - Rich plugin ecosystem (autosuggestions, syntax highlighting)
 - Powerful completion system
@@ -91,12 +98,14 @@ zinit light zdharma-continuum/fast-syntax-highlighting
 - Modern prompt with Starship
 
 ### Negative
+
 - Requires zsh installation on some Linux distros
 - Plugin manager adds complexity
 - Some bash-isms need adjustment
 - Turbo mode can cause brief visual delay
 
 ### Neutral
+
 - Users can still use bash for scripts
 - Configuration more complex than vanilla shell
 - Performance monitoring needed

package/docs/adr/ADR-007-multi-shell-parity.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # ADR-007: Multi-Shell Parity Strategy
 
 ## Status
@@ -12,9 +16,10 @@ Accepted
 
 The dotfiles distribution supports three shells: Zsh (default since macOS Catalina), Fish (modern interactive shell), and Nushell (structured data shell). The codebase has 98 alias files and 52+ functions written in POSIX/Bash. Without a parity strategy, each shell gets a fragmented subset of functionality.
 
-**Problem:** Fish had zero access to the alias/function library until v0.2.500 added bridge templates. Nushell had only 6 hardcoded aliases and no function access.
+**Problem:** Fish had zero access to the alias/function library until v0.2.501 added bridge templates. Nushell had only 6 hardcoded aliases and no function access.
 
 **Constraints:**
+
 - Nushell's `source` is parse-time evaluated (no dynamic sourcing)
 - Fish syntax differs significantly from POSIX (no `$()`, different `if`, no `[[`)
 - Maintaining N copies of every alias/function is unsustainable
@@ -31,6 +36,7 @@ Adopt a **hub-and-spoke bridge architecture**:
    - Functions: Chezmoi template-generated `def` wrappers delegating to bash (in `functions.nu.tmpl`)
 
 **Parity tiers:**
+
 - **Tier 1 (Full):** Zsh, Bash — all aliases, functions, lazy loading, cached eval
 - **Tier 2 (Bridged):** Fish — all simple aliases, all functions via wrappers, `_cached_eval` caching
 - **Tier 3 (Compatible):** Nushell — simple aliases (no complex bash syntax), all functions via bash delegation
@@ -38,16 +44,19 @@ Adopt a **hub-and-spoke bridge architecture**:
 ## Consequences
 
 ### Positive
+
 - Single source of truth for aliases and functions
 - Adding a new alias/function automatically propagates to all shells
 - Nushell users get access to 40+ functions that were previously unavailable
 - Fish users get mtime-aware caching via `_cached_eval`
 
 ### Negative
+
 - Complex bash aliases (pipes, conditionals) are skipped for Nushell
 - Function calls in Fish/Nushell incur bash subprocess overhead (~5ms per call)
 - Cache invalidation requires shell restart or manual cache clear
 
 ### Risks
+
 - Nushell's rapid development may break bridge syntax in future versions
 - Very large alias sets may slow Nushell startup during cache generation

package/docs/adr/ADR-008-alias-system-architecture.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # ADR-008: Alias System Architecture
 
 ## Status
@@ -13,6 +17,7 @@ Accepted
 The dotfiles manage 98 alias files across 30+ categories (git, docker, kubernetes, python, security, etc.). These need to load fast, support per-machine toggling, and work across Zsh, Bash, Fish, and Nushell.
 
 **Design questions:**
+
 1. How to organize alias files for maintainability?
 2. How to control which aliases load on which machines?
 3. How to balance startup speed with alias availability?
@@ -47,6 +52,7 @@ Three profiles control alias scope (set in `.chezmoidata.toml`):
 ### Bucket Toggles
 
 Per-category flags in `.chezmoidata.toml` under `[aliases.buckets]`:
+
 ```toml
 [aliases.buckets]
 system = true
@@ -62,6 +68,7 @@ svn = false    # disable on machines without SVN
 ### Function Groups (groups.json)
 
 Functions use a parallel system with `groups.json` as a registry:
+
 - Groups: api, curl, text, system, files, interactive, nav, security, misc
 - Lazy-loaded per group on first invocation
 - Stub functions replaced with real implementations on first call
@@ -69,17 +76,20 @@ Functions use a parallel system with `groups.json` as a registry:
 ## Consequences
 
 ### Positive
+
 - Adding aliases is self-service: create a file in the right category
 - Per-machine customization without forking
 - Lazy loading keeps startup under 200ms even with 98 alias files
 - `groups.json` enables automated bridge generation for Fish/Nushell
 
 ### Negative
+
 - Alias definitions wrap in functions (`set_default_aliases()`) for sourcing safety, adding complexity
 - Two-phase loading means some aliases aren't available until after first prompt
 - Profile/bucket system requires understanding .chezmoidata.toml
 
 ### Trade-offs
+
 - Chose file-per-category over monolithic alias file for maintainability
 - Chose runtime extraction for Fish/Nushell over maintaining parallel definitions
 - Chose lazy loading over compile-time bundling for flexibility

package/docs/adr/ADR-009-wallpaper-driven-theming.md

@@ -0,0 +1,131 @@
+---
+render_with_liquid: false
+---
+
+# ADR-009: Wallpaper-Driven Theming Engine
+
+## Status
+
+Accepted
+
+## Date
+
+2026-05-12
+
+## Context
+
+Most dotfiles distributions ship a small fixed palette (Solarized, Gruvbox,
+Tokyo Night) chosen once and recycled across every terminal, editor, and
+status bar. When the user changes wallpapers — a daily occurrence on macOS
+with HEIC dark/light variants and on Linux with `swww`/`hyprpaper` —
+terminal chrome stays static, creating visual incoherence between the
+chosen wallpaper and the surrounding tooling.
+
+Manual palette switching solves coherence but adds friction: it requires
+the user to (a) generate a palette, (b) regenerate config for every tool
+(`alacritty.toml`, `kitty.conf`, `wezterm.lua`, neovim themes, …), and
+(c) reload each tool. Tools like pywal/wal automate (a) and (b), but
+pywal palettes routinely fail WCAG contrast thresholds (especially for
+bright wallpapers) and lack support for many of the format files this
+project ships.
+
+**Problem:** Reuse the user's chosen wallpaper as the single source of
+truth for terminal + status-bar colors, with accessibility guaranteed and
+no manual regeneration step.
+
+**Constraints:**
+
+- Output must satisfy **WCAG 2.2 AAA contrast** (≥ 7:1 for normal text,
+  ≥ 4.5:1 for large text) — non-negotiable, the dotfiles ship as
+  workstation infrastructure.
+- Palette extraction must work offline on both macOS (HEIC, dynamic
+  wallpapers with embedded dark/light variants) and Linux (PNG/JPEG via
+  `swww`, `hyprpaper`, `feh`, GNOME).
+- Total time from "user changes wallpaper" → "all terminals retinted"
+  must be ≤ 3 seconds (rebuild trigger + write of templated configs).
+- Targets include Warp, iTerm2, Alacritty, Ghostty, Kitty, Wezterm,
+  Tmux, Neovim (multiple themes), VS Code, Firefox theme JSON, Niri
+  borders, Waybar, GTK/Qt (matugen pipeline).
+
+## Decision
+
+Build a self-contained theming engine — `dot theme rebuild` —
+implemented in `scripts/theme/` with the following pipeline:
+
+1. **Source detection** — locate the active wallpaper across macOS
+   (`defaults read … wallpaper`), GNOME/dconf, KDE, Niri, swww,
+   hyprpaper. HEIC dynamic wallpapers decompose into dark and light
+   variants; both feed the engine.
+
+2. **Color extraction** — **K-Means clustering in CIELAB** (not RGB).
+   CIELAB is perceptually uniform, so distances correlate with the way
+   humans see color similarity. 8-cluster K-Means yields a 16-color
+   ANSI palette (8 normal + 8 bright) plus 4 accent slots.
+
+3. **Contrast enforcement** — compute WCAG 2.2 contrast against the
+   chosen background; nudge each foreground hue along the lightness
+   axis until the ratio passes AAA. The nudge stays within the cluster
+   to preserve aesthetic intent. If AAA cannot be reached, fall back to
+   AA with a logged warning (never silently regress).
+
+4. **Format generation** — emit one canonical TOML palette to
+   `.chezmoidata/themes.toml`, then run `chezmoi apply` so every
+   theme-aware template (terminals, editors, status bars, browsers)
+   regenerates from a single declarative source.
+
+5. **Companion pipelines** — `dot-theme-sync` feeds the same accent
+   colors to **matugen** for Material You-style GTK/Qt theming on
+   Linux, keeping desktop chrome in lockstep with the terminal.
+
+The whole flow is idempotent (`chezmoi apply` is no-op if nothing
+changed), repeatable, and tested under `tests/unit/theme/`.
+
+## Consequences
+
+### Positive
+
+- Single source of truth: change the wallpaper, every tool retints in
+  one keystroke.
+- Accessibility is structural, not opt-in — every shipped palette
+  passes WCAG AAA before it touches a config file.
+- No competing "premium" dotfiles distribution (mathiasbynens, holman,
+  paulirish, omakub) ships anything similar. The engine is a defining
+  differentiator and surfaced in the README hero.
+- Reuses chezmoi's templating — no new templating layer to maintain.
+
+### Negative
+
+- K-Means on a 4K wallpaper takes ~500–800 ms; cached after first run,
+  but the cold path is non-trivial.
+- HEIC handling on Linux requires `libheif` (extra dep on Debian/Ubuntu
+  before 24.04).
+- Contrast enforcement can produce slightly different palettes from the
+  same wallpaper across major OS versions when system color profiles
+  differ (mitigated by snapshot tests).
+
+### Risks
+
+- Wallpapers with extreme dynamic range (pure-white backgrounds, deep
+  monochrome) may fail to produce an aesthetically pleasing 16-color
+  palette even when WCAG AAA is satisfied. Mitigation: maintainer
+  curation of a fallback theme set in `.chezmoidata/themes.toml`.
+- Future Wayland compositors may not expose a stable wallpaper-detection
+  API. The engine isolates source detection in a single module so the
+  blast radius of compositor churn is one file.
+
+## Alternatives Considered
+
+| Alternative | Why rejected |
+|---|---|
+| pywal/wal | RGB K-Means, no WCAG enforcement, limited target list. |
+| matugen alone | Excellent for GTK/Qt; not terminal-aware. We use it *in addition*, not instead. |
+| Static curated themes (Tokyo Night et al.) | Loses the "wallpaper coherence" property that motivates the whole project. |
+| Hand-roll per-terminal scripts | Doesn't compose with chezmoi; loses the single-source-of-truth invariant. |
+
+## References
+
+- WCAG 2.2 contrast: <https://www.w3.org/TR/WCAG22/#contrast-minimum>
+- CIELAB color space: <https://en.wikipedia.org/wiki/CIELAB_color_space>
+- `scripts/theme/` — engine source
+- `.chezmoidata/themes.toml` — output palette schema
+- Issue #873 — captures this ADR alongside `llms.txt`