@sebastienrousseau/dotfiles 0.2.520 → 0.2.521

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

@@ -1,62 +0,0 @@
----
-render_with_liquid: false
----
-
-# ADR-007: Multi-Shell Parity Strategy
-
-## Status
-
-Accepted
-
-## Date
-
-2026-03-08
-
-## Context
-
-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.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
-
-## Decision
-
-Adopt a **hub-and-spoke bridge architecture**:
-
-1. **Hub:** Canonical definitions live in `.chezmoitemplates/aliases/` (Bash/POSIX) and `.chezmoitemplates/functions/` (Bash)
-2. **Bash/Zsh spoke:** Direct inclusion via `90-ux-aliases.sh.tmpl` and `50-logic-functions.sh.tmpl`
-3. **Fish spoke:** Runtime bash bridge with caching (`aliases.fish.tmpl`, `functions.fish.tmpl`)
-4. **Nushell spoke:** Hybrid approach:
-   - Aliases: Runtime bash extraction cached to `~/.cache/nushell/bash-aliases.nu` (in `env.nu.tmpl`), sourced by `aliases.nu.tmpl`
-   - 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
-
-## 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,95 +0,0 @@
----
-render_with_liquid: false
----
-
-# ADR-008: Alias System Architecture
-
-## Status
-
-Accepted
-
-## Date
-
-2026-03-08
-
-## Context
-
-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?
-4. How to bridge POSIX aliases to non-POSIX shells?
-
-## Decision
-
-### Organization
-
-Aliases are organized by tool/domain in `.chezmoitemplates/aliases/<category>/<name>.aliases.sh`:
-
-```text
-aliases/
-  git/git.aliases.sh, signing.aliases.sh
-  docker/docker.aliases.sh
-  kubernetes/kubernetes.aliases.sh
-  security/crypto-utils.aliases.sh, ssh-keys.aliases.sh, ...
-  default/default.aliases.sh
-  ...
-```
-
-### Profile Tiers
-
-Three profiles control alias scope (set in `.chezmoidata.toml`):
-
-| Profile | Scope | Use Case |
-|---------|-------|----------|
-| `minimal` | Core only, excludes interactive/sudo | Servers, containers |
-| `standard` | All core + selected ecosystem | Laptops, workstations |
-| `full` | Everything including heavy/specialized | Dev machines |
-
-### Bucket Toggles
-
-Per-category flags in `.chezmoidata.toml` under `[aliases.buckets]`:
-
-```toml
-[aliases.buckets]
-system = true
-svn = false    # disable on machines without SVN
-```
-
-### Two-Phase Loading
-
-1. **Eager (90-ux-aliases.sh):** Core categories loaded at shell startup (~40KB). Includes: archives, cd, clear, configuration, default, diagnostics, disk-usage, editor, git, interactive, installer, mkdir, modern, ps, rsync, sudo, system.
-
-2. **Lazy (91-ux-aliases-lazy.sh):** Ecosystem aliases deferred until first prompt via `precmd` hook. Includes: docker, kubernetes, terraform, gcloud, python, npm, rust, security, etc.
-
-### 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
-
-## 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

@@ -1,131 +0,0 @@
----
-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

@@ -1,144 +0,0 @@
----
-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

@@ -1,144 +0,0 @@
----
-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`](https://github.com/sebastienrousseau/dotfiles/blob/main/defaults/dot_config/nushell/cached_eval.nu) — the new module.
-- [`dot_config/nushell/env.nu.tmpl`](https://github.com/sebastienrousseau/dotfiles/blob/main/defaults/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/ADR-012-ai-fleet-local-proxy.md

@@ -1,79 +0,0 @@
----
-render_with_liquid: false
----
-
-# ADR-012: AI Fleet — Native Local Claude Proxy and Cockpit
-
-## Status
-
-Accepted
-
-## Date
-
-2026-06-27
-
-## Context
-
-The dotfiles manage a fleet of ~18 AI CLIs (claude, codex, copilot, goose,
-crush, amp, cursor-agent, grok, aider, opencode, agy, sgpt, ollama, autohand, vibe,
-qwen, zai, kiro-cli). Three problems had accumulated:
-
-1. **Incoherent command surface.** The fleet was driven by three incompatible
-   shapes — `dot ai <thing>`, `dot <tool>`, and `dot ai-<thing>` — with opaque
-   names (`cl`, `agy`, `dash`) and no stated reason to prefer `dot ai` over
-   running a tool directly.
-2. **No way to share one subscription.** Each tool needed its own provider/key.
-   Running the whole fleet on a single Claude subscription required a gateway,
-   but adding a third-party proxy (e.g. Meridian) meant a new runtime dependency
-   and 7k+ lines of engine to track.
-3. **No unified cockpit.** Status, cost, and launching were scattered.
-
-## Decision
-
-Build the capability **in-tree**, with no third-party runtime dependency, and
-present it behind a flat, verb-first surface modelled on the Claude CLI.
-
-- **Command surface.** A single `dot ai` namespace: bare opens a cockpit; a
-  bare prompt runs a one-shot on Claude; `<tool> "<prompt>"` targets a tool;
-  plus `chat`, `tools`, `install`, `serve`, `cost`, `login`, `doctor`, and a
-  `--style` steering flag. Old forms remain as deprecated aliases that print a
-  one-line hint. (`scripts/dot/commands/ai.sh`, `lib/dot/ai-commands.sh`.)
-- **Local gateway (`dot ai serve`).** `dot-ai-serve` is a stdlib-only Python
-  server that wraps the already-installed `claude` CLI in headless
-  `stream-json` mode and exposes the Anthropic (`/v1/messages`) and OpenAI
-  (`/v1/chat/completions`) protocols. The `claude` CLI owns auth, caching, and
-  rate limits — the server only translates wire formats. There is **no API key
-  anywhere**; the native Claude session is the credential.
-- **Routing safety.** The primary `claude` is **never** routed through the
-  gateway (it keeps its native session and claude.ai connectors). Routing is
-  applied per-invocation to non-Claude tools only and is never written into the
-  interactive shell environment.
-- **Cockpit (`dot-ai-tui`).** A Bubble Tea (Go) TUI built on `chezmoi apply`
-  via the mise-managed Go toolchain. It shells out to the `dot ai` verbs so
-  behaviour has one source of truth.
-
-## Consequences
-
-- **No new dependency for the headline feature.** The gateway leans on the
-  `claude` CLI the user already has; the cockpit is the only Go artefact and is
-  opt-in (built when `DOTFILES_AI` is set or already installed).
-- **Single source of truth.** The cockpit and completions both derive from the
-  `ai.sh` verb dispatch; a completion-parity test and the docs-coverage contract
-  keep them from drifting.
-- **Scope (v2).** The gateway does chat/completions for both protocols with
-  real token-by-token streaming, model routing/aliases, cost metering
-  (`/metrics`, `/v1/usage`), an optional daily budget cap, `/v1/models`, and
-  `/health`. Because it wraps the `claude` CLI (an agent, not the raw API),
-  tool-call passthrough and multimodal image input are handled gracefully but
-  not forwarded, and session resumption stays out of scope — documented in
-  [`docs/AI.md`](../AI.md).
-- **Naming churn.** Existing muscle memory (`dot cl`, `dot ai dashboard`,
-  `dot ai proxy`) is preserved via deprecated aliases, so nothing breaks while
-  users migrate.
-
-## References
-
-- [`docs/AI.md`](../AI.md) — user guide for the full surface
-- [ADR-004](ADR-004-cli-architecture.md) — the `dot` CLI wrapper this extends
-- [ADR-008](ADR-008-alias-system-architecture.md) — the alias system the
-  deprecated bridges live in