@sebastienrousseau/dotfiles 0.2.500 → 0.2.502

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`

package/docs/adr/ADR-010-starship-transient-prompt.md

@@ -0,0 +1,144 @@
+---
+render_with_liquid: false
+---
+
+# ADR-010: Enable Starship Transient Prompt in Zsh and Fish
+
+## Status
+
+Accepted
+
+## Date
+
+2026-05-12
+
+## Context
+
+Starship is the prompt renderer for both zsh and fish in this
+distribution (pinned via `mise.toml`: `starship = "1.24.2"`).
+A typical Starship prompt for this project renders 4–6 lines including
+the directory, git branch + dirty markers, language toolchain version,
+duration of the previous command, and a final `❯` line.
+
+By default Starship emits this multi-line prompt on **every** previous
+command as well as the current one. After 50 commands in a session, the
+terminal scrollback contains 200–300 lines of historical prompts — most
+of which only convey context that was relevant at the time the command
+ran. Search through scrollback (Ctrl-r history, copy-paste, screenshots,
+asciinema replay) is noisy.
+
+Starship 1.24+ supports a **transient prompt** feature: when a command
+finishes, the prompt that produced it is rewritten to a compact form
+(e.g., `❯`) and the full prompt is re-emitted only at the live editing
+line. The current command always shows the full prompt; history shows
+only the compact form.
+
+**Problem:** Reduce scrollback noise without sacrificing the live prompt's
+rich context, and apply it consistently across the two interactive
+shells we support as first-class.
+
+**Constraints:**
+
+- Must work in zsh and fish (the two Tier-1 shells per ADR-007).
+- Must not interfere with `_cached_eval`'s startup-cost optimization
+  (the transient hook fires per-prompt, not per-shell-start).
+- Must not break copy-paste of previous commands: the compact line
+  must still be `❯` (or similar) so `<Ctrl-shift-c>` over scrollback
+  yields runnable shell content if the user includes the prompt.
+
+## Decision
+
+Call Starship's `enable_transience` shell function after the cached
+`starship init` runs in each shell. We share one `starship.toml.tmpl`
+across both shells; the transient prompt content is the existing
+`[character]` block (no separate `[transient_*]` section needed).
+
+- **Fish**: `dot_config/fish/conf.d/init.fish.tmpl` calls
+  `enable_transience` once the function is defined. `starship init
+  fish` defines it via `--print-full-init`. Result: `$fish_transient_prompt`
+  flips to `1` and the Enter handler is bound to
+  `__starship_transient_execute`. The compact prompt collapses past
+  scrollback as soon as the next command runs.
+
+- **Zsh**: `dot_config/zsh/dot_zshrc.tmpl` carries the same
+  `enable_transience` call, guarded by
+  `(( ${+functions[enable_transience]} ))`. **Upstream Starship does
+  not ship a zsh-side `enable_transience` function yet** (tracked by
+  [starship/starship#3522](https://github.com/starship/starship/issues/3522)).
+  The guard returns 0, the block no-ops, and zsh keeps its full multi-
+  line prompt in scrollback for now. The code is a forward-compatibility
+  hook: when upstream ships the zsh function, the feature activates
+  automatically on the next `mise upgrade starship` with no zshrc edit.
+
+  Alternatives we rejected for zsh:
+
+  - **Roll our own `zle` widget that rewrites `$PROMPT` on Enter.**
+    Possible (the standard recipe overrides `accept-line` with a
+    transient widget). Rejected because:
+    (a) any hand-rolled implementation will conflict with upstream
+        once they ship the official function, forcing a removal,
+    (b) Starship's prompt is multi-line and ANSI-coloured; correctly
+        rewriting it from a custom widget requires duplicating
+        Starship's escape-code generation, which drifts with every
+        Starship release,
+    (c) it'd run inside `_cached_eval`'s eager-init path, complicating
+        the cache-invalidation semantics we documented in ADR-002.
+  - **Third-party zsh plugin (e.g. zsh-autocomplete's transient mode).**
+    Rejected because the upstream Starship fix is in active discussion
+    and a plugin adds a permanent dependency we'd then have to remove.
+  - **Disable zsh transient until upstream lands.** The current state.
+    Zsh users see the same scrollback density they had before this PR;
+    the visible improvement is fish-only. Honest trade-off.
+
+- **Transient prompt content**: `❯` plus optional exit-code dot
+  (red dot if `$status != 0`). Keep it 1–3 characters so scrollback
+  density actually improves.
+
+The toggle is exposed in `.chezmoidata.toml` as
+`features.starship_transient = true`. Users on bandwidth-constrained
+terminals (slow SSH, serial console) can flip it off without editing
+the canonical config.
+
+## Consequences
+
+### Positive (fish only, until upstream lands zsh support)
+
+- Scrollback is 4–5× denser **in fish**. A 100-command session that previously
+  filled the screen 20× over now fills it ~4×.
+- Asciinema recordings (relevant for the showcase commits in #874)
+  read much more naturally — fewer screens of historical prompts
+  between actions.
+- The live prompt still surfaces all the rich context Starship was
+  configured for; only history is compacted.
+
+### Negative
+
+- Slightly more complex Starship config; the maintainer must remember
+  that `[character]` and `[transient_*]` are distinct modules.
+- Users who rely on visual scanning of historical prompts (e.g., "what
+  branch was I on when I ran that?") lose that signal. Mitigation: the
+  feature flag.
+
+### Risks
+
+- Starship's transient API is stable since 1.16 (2023) but the exact
+  config surface evolves. If Starship breaks the schema in a future
+  major, the pinned version in `mise.toml` insulates us; we vet new
+  releases through `dot upgrade --dry-run` before bumping.
+
+## Alternatives Considered
+
+| Alternative | Why rejected |
+|---|---|
+| Single-line Starship prompt | Sacrifices live-prompt richness for the same scrollback-density goal. The transient feature gives both. |
+| Custom zsh `precmd` rewriter | Would have to be reimplemented in fish. Starship already solved it. |
+| Disable Starship entirely on history | Loses the whole reason we use Starship. |
+
+## References
+
+- Starship transient prompt docs:
+  <https://starship.rs/advanced-config/#transientprompt-and-transientrightprompt-in-zsh>
+- ADR-002 (Shell Performance Optimization) — establishes the
+  `_cached_eval` constraint this ADR respects.
+- ADR-007 (Multi-Shell Parity) — establishes zsh + fish as Tier-1.
+- Issue #873 — captures this ADR alongside `llms.txt`.

package/docs/adr/ADR-011-nushell-tier3-keep.md

@@ -0,0 +1,144 @@
+---
+render_with_liquid: false
+---
+
+# ADR-011: Keep Nushell as Tier-3 Reference with Minimum-Viable Caching
+
+## Status
+
+Accepted
+
+## Date
+
+2026-05-13
+
+## Context
+
+ADR-007 (Multi-Shell Parity Strategy) classified the three supported
+shells:
+
+| Tier | Shells | Definition |
+|---|---|---|
+| Tier 1 (Full) | zsh, bash | Native aliases, functions, lazy loading, `_cached_eval` |
+| Tier 2 (Bridged) | fish | Aliases + functions via bridge, `_cached_eval` |
+| Tier 3 (Compatible) | nushell | Simple aliases only, functions via bash delegation |
+
+The 2026 audit (slice 3 of #880's deep-dive) flagged Nushell as a
+maintenance candidate:
+
+- < 5% feature parity with zsh.
+- No async / deferred-load support.
+- No equivalent of `_cached_eval` — meaning every Nushell start spawns
+  `starship init nu`, `mise activate nu`, `zoxide init nushell`,
+  `atuin init nu` as fresh subprocesses, costing 100–200 ms aggregated.
+- 5 config files (`config.nu.tmpl`, `env.nu.tmpl`, `aliases.nu`,
+  `completions.nu.tmpl`, `functions.nu.tmpl`) totalling ~270 lines —
+  enough to be meaningful, not enough to be self-sustaining.
+
+Three paths were proposed:
+
+1. **Keep as-is** — accept the gap, defer maintenance.
+2. **Reduce to a stub** — leave the config but stop investing.
+3. **Remove entirely** — delete all references.
+
+## Decision
+
+**Keep Nushell as Tier-3 with explicit limitations + a minimum-viable
+`_cached_eval` equivalent.**
+
+Specifically:
+
+- Ship `dot_config/nushell/cached_eval.nu` — a Nushell module that
+  ports the binary-mtime-based init caching pattern from zsh/fish.
+  It handles the four tools that matter most for shell start:
+  starship, mise, zoxide, atuin. See the Nushell-specific tradeoffs
+  in the "Consequences" section below.
+- Wire `env.nu.tmpl` to use the new module so subsequent shells skip
+  the subprocess spawns when binaries haven't moved.
+- Continue maintaining the existing `aliases.nu` (hand-curated simple
+  aliases — `l`, `ll`, `la`, etc.) but accept that the bash-bridge
+  approach for full alias parity isn't worth the complexity.
+- Update `README.md`'s shell list to call Nushell out as "best-effort
+  / Tier-3" so users have correct expectations.
+- Reject the "remove entirely" option for now (see Rationale below).
+
+## Rationale
+
+**Why not remove**: Nushell is shipped with the canonical `mise`
+toolchain in this repo (it's installable via `mise install nushell`)
+and is gaining adoption in the Rust + data-engineering communities
+that overlap with this distribution's audience. Removing it would
+break promises to a small-but-vocal segment of users. The maintenance
+cost of the current 270-line surface is low.
+
+**Why not reduce to a stub**: A stub config is worse than the current
+moderate config — users who type `nu` and get a featureless shell
+without any of the integrations the README promised would feel
+betrayed. Either we keep the shell working well enough to use, or we
+delete it.
+
+**Why the minimum-viable cache layer**: The biggest waste on every
+Nushell start was the four uncached subprocess spawns
+(`starship init nu` etc.). Adding mtime-based caching for those costs
+~50 lines of Nushell code and saves 100–200 ms per shell. That's the
+cheapest meaningful improvement; deeper investments (async hydration,
+plugin system, bash bridge for aliases) await an actual user request.
+
+## Consequences
+
+### Positive
+
+- Nushell starts substantially faster than before (TBD — needs
+  measurement on a host with all four tools installed). The
+  subprocess elimination saves ~50–80 ms per cached tool, per cold
+  shell after the cache is populated.
+- The mtime-invalidation pattern matches what zsh / fish do, so a
+  contributor familiar with one of the other shells can read the
+  Nushell code without learning a new mental model.
+- Explicit Tier-3 documentation avoids the "wait, this is supposed to
+  be at parity" surprise.
+
+### Negative
+
+- Nushell's parse-time evaluator means we can't wrap source calls in
+  the cache function — the caller has to `source <path>` directly.
+  Slightly more boilerplate than the zsh/fish APIs.
+- No malware-pattern screening in the cached output. The zsh / fish
+  implementations grep for `curl ... | sh`, `nc -e`, etc. before
+  sourcing; the Nushell version trusts its inputs. For the four tools
+  we ship (`starship`, `mise`, `zoxide`, `atuin`) this is acceptable
+  — they're official binaries pinned via `mise.toml`. Future tools
+  added to the cache must be similarly trusted.
+- No per-tool timing telemetry. The `EVALCACHE_TIMING` infrastructure
+  zsh has (#863) isn't ported. If Nushell perf becomes a sustained
+  user concern, this is the next layer to add.
+
+### Risks
+
+- Nushell's syntax evolves quickly between 0.x releases. The
+  `cached_eval.nu` module uses `path exists`, `ls | get -i modified`,
+  and `run-external` which have been stable since 0.86 (Q3 2024).
+  If a future Nushell release breaks the API, the module fails fast
+  (saving an empty cache file) rather than corrupting state.
+- Cache invalidation by mtime is fragile when the user installs a
+  tool via a non-mtime-respecting method (e.g. unpacking a tarball
+  with `--no-touch-mtimes`). The fallback is the user running
+  `dot prewarm` or deleting `~/.cache/nushell/*.nu`. Documented in
+  `docs/operations/PERFORMANCE.md`.
+
+## Alternatives Considered
+
+| Alternative | Why rejected |
+|---|---|
+| **Bash bridge for full alias parity** | Adds a `bash --norc --noprofile -c '...'` subprocess on every Nushell start (~30 ms). Defeats the perf gain from the cache layer. |
+| **Port `_cached_eval` 1:1 (malware screen + JSONL telemetry)** | The full zsh implementation is 100+ lines. The Nushell version covers the 80% case at 50 lines; the remaining 20% (advanced features) aren't load-bearing for Tier-3 status. |
+| **Delete Nushell entirely** | See "Why not remove" above. |
+| **Reduce to a stub** | See "Why not reduce to a stub" above. |
+
+## References
+
+- [`dot_config/nushell/cached_eval.nu`](../../dot_config/nushell/cached_eval.nu) — the new module.
+- [`dot_config/nushell/env.nu.tmpl`](../../dot_config/nushell/env.nu.tmpl) — adopter.
+- ADR-007 (Multi-Shell Parity Strategy) — establishes the tier definitions.
+- ADR-002 (Shell Performance Optimization Strategy) — establishes `_cached_eval` semantics this module ports.
+- Issue [#880](https://github.com/sebastienrousseau/dotfiles/issues/880).

package/docs/adr/README.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Architecture Decision Records
 
 This directory contains Architecture Decision Records (ADRs) that document
@@ -15,6 +19,9 @@ significant architectural decisions made in this project.
 | [ADR-006](ADR-006-shell-selection.md) | Zsh as Default Shell | Accepted |
 | [ADR-007](ADR-007-multi-shell-parity.md) | Multi-Shell Parity Strategy | Accepted |
 | [ADR-008](ADR-008-alias-system-architecture.md) | Alias System Architecture | Accepted |
+| [ADR-009](ADR-009-wallpaper-driven-theming.md) | Wallpaper-Driven Theming Engine | Accepted |
+| [ADR-010](ADR-010-starship-transient-prompt.md) | Enable Starship Transient Prompt in Zsh and Fish | Accepted |
+| [ADR-011](ADR-011-nushell-tier3-keep.md) | Keep Nushell as Tier-3 Reference with Minimum-Viable Caching | Accepted |
 
 ## ADR Format
 

package/docs/architecture/ARCHITECTURE.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Architecture
 
 Core architectural decisions and system design of the dotfiles shell distribution.

package/docs/architecture/INTEROP.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Cross-Platform Interoperability
 
 How dotfiles commands and shims map across macOS, Linux, and WSL2.
@@ -24,13 +28,17 @@ How dotfiles commands and shims map across macOS, Linux, and WSL2.
 ## Troubleshooting
 
 ### WSL2 IO Latency
+
 Keep projects in the Linux filesystem (`~/...`), not under `/mnt/c/`.
 
 ### WSL2 Windows Binary Path
+
 If you've disabled WSL path sharing, make sure Windows-side binaries like `clip.exe` and `explorer.exe` are still reachable in `$PATH`.
 
 ### macOS Permissions
+
 Grant your terminal "Full Disk Access" in System Settings so dotfiles can manage all configurations.
 
 ### Linux GUI Fallbacks
+
 In headless environments, GUI commands like `cb` and `open` fall back to `gum log` or terminal bell instead of hanging.

package/docs/architecture/REPO_LAYOUT.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 <!-- Copyright (c) 2015-2026 Dotfiles. All rights reserved. -->
 
 # Repository Layout
@@ -154,7 +158,7 @@ the repo itself.
 
 | Path                                  | Purpose                                                                    |
 |---------------------------------------|----------------------------------------------------------------------------|
-| `docs/manual/`                        | 26-page GNU-Stow-style reference manual (the v0.2.500 feature)             |
+| `docs/manual/`                        | 26-page GNU-Stow-style reference manual (the v0.2.501 feature)             |
 | `docs/architecture/`                  | This file + core architecture docs (ARCHITECTURE, INTEROP, fleet, walkthrough) |
 | `docs/operations/`                    | Runbooks, traceability matrix, migration notes                             |
 | `docs/reference/`                     | Command/config reference material                                           |

package/docs/architecture/WALKTHROUGH.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Walkthrough
 
 A hands-on tour of the dotfiles after installation. Run each step in your terminal to get comfortable with what's available.

package/docs/architecture/fleet-deployment.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Fleet Deployment Architecture
 
 ## Deployment Flow

package/docs/archive/EUXIS_2026_REVIEW.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Euxis 2026 Architecture & Product Review
 
 This review translates the current dotfiles CLI stack into an Apple-tier product strategy:
@@ -76,18 +80,22 @@ Added `scripts/tests/unit/test_dot_lib_platform.sh`:
 ## File-by-file next refactors (high ROI)
 
 1. `scripts/dot/commands/tools.sh`
+
 - Split `cmd_aliases` into submodule file.
 - Replace repeated `command -v` checks with cached capability map.
 
-2. `dot_config/zsh/dot_zshrc.tmpl`
+1. `dot_config/zsh/dot_zshrc.tmpl`
+
 - Add startup budget guard (record startup time; warn >400ms).
 - Move optional integrations behind capability checks generated once/session.
 
-3. `scripts/ops/health-check.sh`
+1. `scripts/ops/health-check.sh`
+
 - Import `platform.sh`, unify WSL/macOS/Linux branch logic.
 - Emit machine-readable JSON summary for UI frontends.
 
-4. `scripts/diagnostics/perf.sh`
+1. `scripts/diagnostics/perf.sh`
+
 - Add percentile reporting (P50/P95 over 10 runs).
 - Add regression threshold with actionable remediation hints.