@sebastienrousseau/dotfiles 0.2.519 → 0.2.521

package/docs/archive/PLAN.md

@@ -1,199 +0,0 @@
----
-render_with_liquid: false
----
-
-# Universal Configuration Plan (Chezmoi)
-
-... [Previous Sections Unchanged] ...
-
-# Phase 15: Operational Documentation [COMPLETED]
-
-- [x] **Guide**: Created `OPERATIONS.md`.
-
-# Phase 16: Final Release Verification [COMPLETED]
-
-- [x] **Verification**: All systems passed.
-
-# Phase 17: Structural Optimizations (v0.3.0)
-
-## Goal
-
-Implement structural improvements for better organization and maintainability, anticipating v0.3.0.
-
-## Proposed Changes
-
-### [REFACTOR] Semantic Organization
-
-- **Move**: `dot_config/dotfiles` -> `dot_config/shell`.
-- **Reason**: `dotfiles` is redundant inside a dotfiles repo. `shell` describes the content (aliases, paths, functions).
-- **Update**: Update references in `dot_zshrc.tmpl` and install scripts.
-
-### [REFACTOR] Script Installation
-
-- **Move**: `bin/` -> `dot_local/bin/`.
-- **Reason**: Ensures scripts are automatically installed to `~/.local/bin` (user PATH).
-
-### [CLEANUP] Remove Legacy Files
-
-- **Delete**: `Makefile`, `package.json`.
-- **Reason**: Replaced by `chezmoi` and GitHub Actions.
-
-### [REFACTOR] Script Segregation
-
-- **Split**: `run_onchange_install_packages.sh.tmpl` into:
-  - `run_onchange_darwin_install-packages.sh.tmpl` (Homebrew)
-  - `run_onchange_linux_install-packages.sh.tmpl` (Apt)
-  - `run_onchange_after_install-vim-plug.sh.tmpl` (Universal)
-- **Reason**: Improves readability and maintainability.
-
-# Phase 18: Component Documentation Polish [COMPLETED]
-
-## Goal
-
-Update component documentation (`aliases`, `functions`, `paths`) to match the new `chezmoi` architecture and ensure accuracy.
-
-## Changes
-
-- **Aliases**: Updated `aliases/README.md` to explain modular `*.aliases.sh` loading.
-- **Functions**: Updated `functions/README.md` to remove legacy install instructions.
-- **Paths**: Updated `paths/README.md` to clarify precedence and `chezmoi` integration.
-- **Cleanup**: Standardized all nested alias READMEs to remove legacy HTML artifacts and restore banners.
-
-# Phase 19: Toolchain Expansion [COMPLETED]
-
-## Goal
-
-Add comprehensive support for modern DevOps/Cloud engineering tools.
-
-## Proposed Changes
-
-### [NEW] Aliases
-
-- **Kubernetes**: `kubectl` shortcuts (`k`), `helm`, `k9s`.
-- **IaC**: `terraform` (`tf`), `opentofu`, `ansible`.
-- **Languages**: `go` (`g`), `yarn`, `uv` (modern Python).
-- **Diagnostics**: `jq`, `yq`, `nc`, `curlie`.
-- **Structure**: Each component gets its own directory in `.chezmoitemplates/aliases/` with a standard `README.md`.
-
-# Phase 20: Intelligent Assistance [COMPLETED]
-
-## Goal
-
-Integrate AI capabilities and improved help systems.
-
-## Proposed Changes
-
-### [NEW] Functions
-
-- **`dothelp`**: Index and search all aliases/functions with descriptions.
-- **AI Wrappers**: Aliases for `gh copilot`, `fabric`, or generic LLM CLI tools.
-
-# Phase 22: Automated Testing [COMPLETED]
-
-## Goal
-
-Verify the dotfiles work on clean Linux environments.
-
-## Proposed Changes
-
-### [CI] GitHub Actions
-
-- **Container Job**: Run `chezmoi init --apply` inside a localized Docker container (Ubuntu/Fedora) to prove universal compatibility.
-
-# Phase 23: Enterprise Core & Security (The Trust Layer) [COMPLETED]
-
-## Goal
-
-Establish a "Trust Layer" for the dotfiles ecosystem, ensuring supply chain security and configuration integrity.
-
-## Changes
-
-- **SLSA & SBOM**: Implemented `security-release.yml` for provenance and SBOM generation.
-- **Signing**: Created `enable-signing` wizard alias for streamlined GPG/SSH configuration.
-- **Immutability**: Created `lock-configs.sh` script and `lock-configs`/`unlock-configs` aliases.
-
-- **Immutability**: Created `lock-configs.sh` script and `lock-configs`/`unlock-configs` aliases.
-
-# Phase 27: Self-Healing & Diagnostics [COMPLETED]
-
-## Goal
-
-Enable the system to self-diagnose and repair configuration drift.
-
-## Changes
-
-- **Scripts**: Created `scripts/diagnostics/doctor.sh` for system health checks.
-- **Aliases**: Added `dot doctor`, `dot drift` (`chezmoi verify`), and `dot heal` (`chezmoi apply`).
-
-# Phase 51: Regulatory Compliance [COMPLETED]
-
-## Goal
-
-Document and enforce compliance with SOC2, ISO, and GDPR standards.
-
-## Changes
-
-- **Documentation**: Created `COMPLIANCE.md` with control mappings.
-- **Privacy**: Added `privacy-mode` alias to disable CLI telemetry.
-- **Audit**: Added `dot audit` alias for tracking changes.
-
-# Phase 54: macOS Deep Integration [COMPLETED]
-
-## Goal
-
-Harden and optimize the macOS environment via code.
-
-## Changes
-
-- **Defaults**: Created `run_onchange_darwin_defaults.sh.tmpl` to apply secure/optimized `defaults`.
-- **Hardening**: Enabled screensaver passwords, firewall settings, and disabled guest access.
-
-## Goal
-
-Ensure legal compliance and proper attribution for the open-source project.
-
-## Changes
-
-- **Licensing**: Added `scan-licenses` alias (Trivy/FOSSology).
-- **Headers**: Added `add-headers` alias for automated copyright insertion.
-- **Compliance**: Added `check-cla` and `gen-notice` tools.
-
-# Phase 59: Font Typography [COMPLETED]
-
-## Goal
-
-Standardize typography and ensure high-quality font rendering across all environments.
-
-## Proposed Changes
-
-- **Nerd Fonts**: Automate installation of `JetBrainsMono Nerd Font` and `Symbols Nerd Font`.
-- **Fontconfig**: Deploy XML configuration for Linux font rendering (antialiasing, hinting).
-- **Aliases**: `update-fonts` to refresh font caches (`fc-cache`).
-
-# Phase 26: OS Bundling & Compliance [COMPLETED]
-
-## Goal
-
-Prepare the dotfiles for system-wide deployment and ensure strict adherence to standards.
-
-## Proposed Changes
-
-- **XDG Compliance**: Audit `00-default.paths.sh` to ensure all standard XDG variables are exported.
-- **Vendor Hooks**: Update `dot_zshrc.tmpl` to source system-level overrides from `/etc/dotfiles/defaults.d/` (Simulates "site-local" config).
-- **Bundling**: Create `scripts/core/package.sh` to create a distributable tarball and scaffold `.deb`/`.pkg` generation logic.
-
-# Phase 24: The Universal Installer (Zero-Dependency) [COMPLETED]
-
-## Goal
-
-Provide a frictionless, "one-curl" onboarding experience and capabilities to deploy configurations remotely.
-
-## Proposed Changes
-
-- **install.sh**: A standalone, zero-dependency bash script that:
-    1. Detects OS/Arch.
-    2. Installs `chezmoi` (binary or via package manager).
-    3. Initializes the dotfiles repo.
-    4. Runs `chezmoi apply`.
-    5. Uses ANSI colors for a polished "TUI" feel.
-- **Teleportation**: `scripts/ops/teleport.sh` using `chezmoi archive` piped to SSH to ephemeralize configs on remote servers (e.g., `dot teleport user@server`).

package/docs/archive/REPO_AUDIT.md

@@ -1,31 +0,0 @@
----
-render_with_liquid: false
----
-
-# Repo Audit
-
-## Source of truth
-
-- `~/.dotfiles` (chezmoi source directory)
-
-## Key directories
-
-- `.chezmoitemplates/` - templated aliases, functions, paths
-- `dot_config/` - configs mapped into `~/.config`
-- `dot_local/` - binaries and local data (e.g., `dot` CLI)
-- `scripts/` - diagnostics, tests, tooling
-- `tests/` - sandbox Dockerfile
-- `nix/` - optional Nix toolchain
-
-## Notable dependencies
-
-- `chezmoi`
-- `zsh`, `starship`
-- `neovim`
-- `ripgrep`, `fd`, `bat`, `fzf`, `zoxide`
-- `lazygit`
-
-## Notes
-
-- Repo-only files excluded via `.chezmoiignore`.
-- Secrets are handled via `age` + `dot secrets` (see `docs/SECRETS.md`).

package/docs/articles/.pages

@@ -1,6 +0,0 @@
-title: Articles
-nav:
-  - index.md
-  - 2026-07-05-fish-startup-abbr.md
-  - 2026-07-05-master-to-main-rename-runbook.md
-  - 2026-07-05-custom-mkdocs-material-dark-theme.md

package/docs/articles/2026-07-05-custom-mkdocs-material-dark-theme.md

@@ -1,216 +0,0 @@
----
-title: "Custom Documentation Sites in 2026: Building a Distinctive Dark-Themed Developer Reference on MkDocs Material Without Forking"
-description: A three-file recipe for a bespoke MkDocs Material theme — terminal-green on near-black, custom hero + card grid, hash-locked build. No custom_dir, no fork.
-date: 2026-07-05
----
-
-# Custom Documentation Sites in 2026: Building a Distinctive Dark-Themed Developer Reference on MkDocs Material Without Forking
-
-*Documentation is the public API surface of an open-source project; the difference between the default Material theme and a bespoke palette is the difference between "reads like every other project" and "reads like this specific project".*
-
-*Sebastien Rousseau · Published 5 Jul 2026 · 11 min read*
-
-## Why Documentation Aesthetics Matter in 2026 #
-
-An open-source project's documentation site is the first surface an evaluator touches — before the README, before the release notes, before the code. In 2026, the density of developer-tool competition means that visual differentiation carries measurable weight: does the site feel like a curated product, or does it feel like a Jekyll-Cayman default from 2019? The felt distinction shapes adoption decisions before the reader has read a single sentence.
-
-The reference standard for "distinctive open-source documentation" is [docs.n8n.io](https://docs.n8n.io) — dark, polished, opinionated, immediately identifiable as n8n's. n8n runs on GitBook, a commercial SaaS. Most open-source projects, [.dotfiles](https://doc.dotfiles.io) included, cannot justify GitBook's licensing but can invest in MkDocs Material customisation to achieve equivalent visual distinction on an open-source stack.
-
-This article documents the migration of [doc.dotfiles.io](https://doc.dotfiles.io) from Jekyll's Cayman theme (the default when GitHub Pages serves markdown without a MkDocs configuration) to a fully customised MkDocs Material theme with a terminal-green-on-near-black palette, custom typography, and a hero + card-grid landing page.
-
-## The Custom Docs Theme 2026 Architecture Lens #
-
-MkDocs Material's customisation surface has four distinct layers, each with different capabilities and constraints:
-
-| Layer | Design Decision | Why It Matters | Risk if Mishandled |
-|---|---|---|---|
-| **Palette declaration** | `mkdocs.yml` `theme.palette.primary: custom` + `accent: custom` | Signals to MkDocs Material that CSS custom properties will drive the palette rather than a named preset (green, teal, indigo, etc.) | Named presets constrain the palette to Material Design's colour tokens; `custom` unlocks arbitrary hex values via CSS variables |
-| **CSS custom-property overrides** | `docs/stylesheets/extra.css` sets `--md-primary-fg-color`, `--md-accent-fg-color`, `--md-default-bg-color`, `--md-code-bg-color` under `[data-md-color-scheme="slate"]` | The single source of truth for the palette. Every Material component reads from these variables | Overriding component-level CSS rules rather than variables creates unmaintainable per-component drift as MkDocs Material upgrades |
-| **Component restyling** | Same `extra.css` overrides selectors like `.md-header`, `.md-nav__link`, `.grid.cards > ul > li` | Where the "feels bespoke" work happens — spacing, borders, hover states, gradients, backdrop blur | Under-styling produces "Material Design in a different colour"; over-styling drifts away from Material's ergonomic defaults |
-| **Landing-page markup** | `docs/index.md` with Front-Matter `hide: [navigation, toc]` + `<section class="dot-hero">` + `<div class="grid cards" markdown>` | The homepage is the highest-impact surface; it should not look like a table of contents | Default MkDocs Material index reads like documentation; a custom hero reads like a product page |
-
-## Key Documentation-UX Signals #
-
-| Signal | Operational Benchmark | Reference | Technical Platform Implementation |
-|---|---|---|---|
-| **Time-to-first-CTA** | Hero action button visible above the fold in ≤ 100 ms of first-paint | Landing-page conversion norms | Custom hero section with primary and secondary CTAs immediately below the site title |
-| **Palette Distinctiveness** | Primary accent color is unique to the project, not a Material Design preset | Brand recognition | CSS custom property overrides on `[data-md-color-scheme]` selectors |
-| **Reading Contrast** | WCAG AA compliance on all text-on-background pairs | Accessibility gate | `--md-default-fg-color` (`#e4e7ec`) on `--md-default-bg-color` (`#0b0e14`) = 15.6:1 ratio |
-| **Cognitive Load per Section** | Feature-card grid on landing page (visual chunking) rather than a bulleted link list | Landing-page ergonomics | `<div class="grid cards" markdown>` + 8 cards with material icons |
-| **Build Reproducibility** | `mkdocs.yml` + `docs/stylesheets/extra.css` under version control; hashes locked in `requirements-docs.txt` | Supply-chain hygiene | `pip-compile --generate-hashes` + `pip install --require-hashes` in the Pages workflow |
-| **Cache Cost at Edge** | CDN TTL respected; theme changes propagate to `doc.<domain>` within 10 minutes | Deployment latency | Cloudflare (or equivalent) `max-age=600` on the site |
-
-## Diagnosis: What "Default MkDocs Material" Leaves on the Table #
-
-An out-of-the-box MkDocs Material site with `primary: teal, accent: teal` and no `extra_css` is visually acceptable — but it is one of many thousand acceptable sites that look identically acceptable. The named presets are constrained to Google's Material Design palette; the sidebar, header, and content surface all read as "Material default".
-
-For a project positioning itself as "an opinionated developer platform, not a library", the visual signal that the docs are *the product's* docs — not somebody else's — is a marketing surface, not a decoration. The lift is contained to three files:
-
-- `mkdocs.yml` — palette selector configuration
-- `docs/stylesheets/extra.css` — the actual palette + typography + component overrides
-- `docs/index.md` — hero + card grid replacing the default index
-
-No template overrides (`custom_dir`), no plugin authoring, no JavaScript. All the customisation lives in files MkDocs Material is explicitly designed to consume.
-
-## Remediation: The Three-File Custom Theme #
-
-### `mkdocs.yml` Palette Configuration
-
-The magic value that unlocks CSS-driven colours is `primary: custom` (and `accent: custom`). Under `[data-md-color-scheme="slate"]`, MkDocs Material's dark variant, every component reads its colours from CSS custom properties that we get to define.
-
-```yaml
-theme:
-  name: material
-  font:
-    text: Inter
-    code: JetBrains Mono
-  palette:
-    - media: "(prefers-color-scheme: dark)"
-      scheme: slate
-      primary: custom
-      accent: custom
-    - media: "(prefers-color-scheme: light)"
-      scheme: default
-      primary: custom
-      accent: custom
-  features:
-    - navigation.tabs
-    - navigation.tabs.sticky
-    - navigation.footer
-    - content.code.copy
-
-extra_css:
-  - stylesheets/extra.css
-```
-
-The `navigation.tabs.sticky` feature keeps the top-level navigation visible on scroll, which pairs with the hero + card grid to keep the site feeling like a product page rather than a scrolling article.
-
-### `docs/stylesheets/extra.css` — Palette + Component Overrides
-
-The stylesheet is organised in five zones: CSS custom properties for the palette, typography, dark-scheme palette overrides, per-component restyling, and the custom hero + grid-card styles.
-
-```css
-:root {
-  --dot-green: #7ee787;         /* terminal green — primary */
-  --dot-green-bright: #b0f5b7;  /* hover / focused */
-  --dot-green-dim: #4a9153;     /* muted */
-  --dot-bg: #0b0e14;            /* near-black base */
-  --dot-bg-elev: #111621;       /* elevated card */
-  --dot-fg: #e4e7ec;
-  --dot-fg-muted: #94a3b8;
-  --dot-border: #1f2937;
-}
-
-[data-md-color-scheme="slate"] {
-  --md-default-bg-color: var(--dot-bg);
-  --md-default-fg-color: var(--dot-fg);
-  --md-primary-fg-color: var(--dot-green);
-  --md-accent-fg-color: var(--dot-green-bright);
-  --md-typeset-a-color: var(--dot-green);
-  --md-code-bg-color: #161b26;
-}
-```
-
-The choice of `#7ee787` (GitHub's terminal green) as the accent is deliberate: it reads as "developer tool" to the target audience without being GitHub-branded, and the WCAG contrast on the `#0b0e14` background exceeds 12:1 for text and 4.5:1 for the accent-on-background — comfortably above AA thresholds.
-
-Component overrides are targeted at the highest-impact surfaces:
-
-```css
-/* Header: blurred backdrop-saturate for a floating feel */
-.md-header {
-  background-color: rgba(11, 14, 20, 0.92);
-  backdrop-filter: saturate(180%) blur(12px);
-  border-bottom: 1px solid var(--dot-border);
-}
-
-/* Grid cards on landing page — hover lift + accent glow */
-.md-typeset .grid.cards > :is(ul, ol) > li {
-  background: var(--dot-bg-elev);
-  border: 1px solid var(--dot-border);
-  border-radius: 12px;
-  transition: transform 180ms ease, border-color 180ms ease;
-}
-.md-typeset .grid.cards > :is(ul, ol) > li:hover {
-  transform: translateY(-2px);
-  border-color: rgba(126, 231, 135, 0.35);
-  box-shadow: 0 8px 24px -8px rgba(0, 0, 0, 0.5);
-}
-```
-
-### `docs/index.md` — Hero + Grid Cards
-
-The landing page is not documentation — it is a product surface. MkDocs Material's `md_in_html` extension allows Markdown to nest inside a custom HTML section:
-
-```markdown
----
-hide:
-  - navigation
-  - toc
----
-
-<section class="dot-hero" markdown>
-
-# .dotfiles
-
-<p class="tagline">Cross-platform, signed, local-first dotfiles…</p>
-
-<div class="buttons">
-  <a class="primary" href="guides/INSTALL/">Install →</a>
-  <a href="https://github.com/sebastienrousseau/dotfiles">GitHub</a>
-</div>
-
-</section>
-
-## What's inside
-
-<div class="grid cards" markdown>
-
-- :material-console:{ .lg .middle } **Multi-shell parity**
-
-    ---
-
-    Bash, Zsh, Fish, Nushell — same aliases, functions, prompt, and completions.
-
-    [→ Shell hub](https://doc.dotfiles.io/reference/UTILS/)
-
-</div>
-```
-
-The `hide: [navigation, toc]` front-matter removes the sidebar and right-column table-of-contents on this page only — the landing page gets the full canvas, sub-pages retain the standard docs layout.
-
-## Verification: Build, Deploy, Contrast #
-
-The custom theme adds ~12 KB of CSS to the built site. Local `mkdocs build --clean` completes in ~2 seconds. The Pages workflow uses hash-locked dependencies (`pip install --require-hashes -r requirements-docs.txt`) to keep the build reproducible across MkDocs Material and its 30+ transitive dependencies.
-
-Accessibility contrast measured on the deployed site:
-
-- Body text (`#e4e7ec` on `#0b0e14`) — **15.6:1** (WCAG AAA)
-- Accent (`#7ee787` on `#0b0e14`) — **12.4:1** (WCAG AAA)
-- Muted text (`#94a3b8` on `#0b0e14`) — **7.2:1** (WCAG AAA)
-
-Cloudflare CDN cache invalidation after Pages deploy: ~10 minutes on `max-age=600`. Fetching the GitHub Pages origin (`sebastienrousseau.github.io/dotfiles/`) reflects the new theme immediately; the CDN-fronted custom domain propagates within one cache TTL.
-
-## Return on Resilience #
-
-| Metric | Before (Jekyll Cayman) | After (Custom MkDocs Material) |
-|---|---|---|
-| Page weight | 2.9 KB | 14.8 KB (compressed 4.2 KB) |
-| Time to visible hero | ~800 ms (no hero) | ~150 ms |
-| WCAG AA compliance | Passes body text; hero absent | Passes AAA on all text pairs |
-| Landing-page CTAs | 0 (link list only) | 4 (primary + 3 secondary) |
-| Visual differentiation from default | Zero | Distinctive palette + hero + grid |
-| Build reproducibility | Jekyll on `github-pages` gem (unpinned transitive deps) | `pip install --require-hashes` (fully locked) |
-
-## Takeaways #
-
-1. **`primary: custom` + `extra_css` beats theme forking.** No `custom_dir`, no Jinja templates, no plugin authoring. All the customisation lives in files MkDocs Material is explicitly designed to consume.
-
-2. **CSS custom properties are the maintainable seam.** Overriding `--md-primary-fg-color` scales; overriding `.md-header a.md-header__button:not(...)` selectors doesn't.
-
-3. **Treat the landing page as a product surface, not documentation.** Front-matter `hide: [navigation, toc]` unlocks the full canvas. Hero + card grid + tabbed quick-start reads as a product page.
-
-4. **Lock the docs-build supply chain.** `pip-compile --generate-hashes` + `pip install --require-hashes` closes the Scorecard `PinnedDependenciesID` alert and prevents transitive-dep drift in Pages deploys.
-
-5. **Measure contrast, not just aesthetics.** WCAG AAA on body text is achievable with the right palette; it's not a tradeoff against distinctiveness.
-
-The reference implementation landed as [PR #960](https://github.com/sebastienrousseau/dotfiles/pull/960) and is live at [doc.dotfiles.io](https://doc.dotfiles.io); the theme source lives at [`docs/stylesheets/extra.css`](https://github.com/sebastienrousseau/dotfiles/blob/main/docs/stylesheets/extra.css).

package/docs/articles/2026-07-05-fish-startup-abbr.md

@@ -1,153 +0,0 @@
----
-title: "Fish Startup in 2026: Cutting Interactive Shell Latency by Half with abbr on Multi-Shell Dotfiles"
-description: Diagnosing and remediating a 232 ms fish cold-start on the .dotfiles multi-shell bridge — one printf format change, one chezmoi hook, half the latency.
-date: 2026-07-05
----
-
-# Fish Startup in 2026: Cutting Interactive Shell Latency by Half with `abbr` on Multi-Shell Dotfiles
-
-*Interactive shells have become the primary interface for AI-augmented development; the difference between a 120 ms and a 230 ms first prompt compounds into measurable engineering-hour loss across a global fleet.*
-
-*Sebastien Rousseau · Published 5 Jul 2026 · 10 min read*
-
-## Why Interactive Shell Latency Matters in 2026 #
-
-The AI-augmented developer opens a terminal dozens of times a day. In fleets running Claude Code, Codex CLI, GitHub Copilot CLI, or agentic frameworks that spawn subshells for every tool call, shell startup latency stops being a personal-comfort metric and becomes a **platform-engineering signal**.
-
-The [.dotfiles reference framework](https://github.com/sebastienrousseau/dotfiles) treats sub-second shell startup as an SLO alongside SLSA-signed releases and MCP boundary enforcement. When a shell exceeds its budget, the framework's `dot health` command reports it as a failing check, not a warning — because a slow prompt on a workstation running 18 concurrent AI agents is a supply-chain-throughput problem, not an aesthetic one.
-
-This article walks through the diagnosis and fix that took Fish cold-start latency from **231 ms → 119 ms** — a 48% reduction — on a workstation carrying ~900 bridged bash aliases into Fish for cross-shell parity. The remediation is a one-line change to a code-generation printf statement, plus a chezmoi hook that moves the cost out of the interactive path.
-
-## The Multi-Shell Bridge 2026 Architecture Lens #
-
-Cross-shell parity — the same aliases, functions, environment, and completions across bash, Zsh, Fish, and Nushell — is a distinct architectural property of a mature dotfiles framework. Each layer of that bridge carries its own performance tax:
-
-| Layer | Design Decision | Why It Matters | Risk if Mishandled |
-|---|---|---|---|
-| **Source of truth** | Bash-hosted alias library (~900 entries) sourced by `zsh` and `bash` natively | Single canonical location prevents drift; matches how most upstream tooling assumes aliases live | Duplication across shells silently diverges; users on Fish or Nushell get a subtly different alias set |
-| **Fish bridge** | `bash --norc --noprofile` subshell dumps `alias -p`, output translated and cached to `~/.cache/fish/bash-aliases.fish` | Fish has no `bash`-sourcing primitive; the bridge is unavoidable | Bridge runs at every shell start unless cached; cache invalidation timing determines the felt cost |
-| **Cache format** | `abbr --add NAME -- VALUE` (this article's change) instead of `alias NAME=VALUE` | Fish's `alias` builtin allocates a function per entry (~183 µs each × 900 entries = ~165 ms); `abbr` is a command-line-time expansion at ~40 µs | Choosing `alias` for the cache format silently caps Fish cold-start at ~230 ms even on a warm cache |
-| **Cache invalidation** | Compare source mtime + first-line format marker | Alias sources change on every `chezmoi apply`, invalidating the cache and forcing regen on the next shell — the exact moment the user opens a terminal to try their changes | Cache regen on the interactive path punishes the shell that opens right after configuration changes |
-| **Pre-warm hook** | `run_onchange_after_` chezmoi hook rebuilds the cache during apply | Moves the ~200 ms regen cost off the user's first prompt into the apply step | Absence of a pre-warm hook makes the first post-apply shell feel broken |
-
-## Key Interactive Shell Performance Signals #
-
-| Signal | Operational Benchmark | Reference | Technical Platform Implementation |
-|---|---|---|---|
-| **Fish cold-start** | ≤ 200 ms first-prompt latency | Interactive-response threshold (Nielsen 1993, still the industry norm) | `hyperfine --warmup 2 'fish -i -c exit'` in CI; regression fails a PR if the median crosses threshold |
-| **Fish warm-start** | ≤ 130 ms after cache is populated | Delta between cold/warm reveals cache-invalidation cost | Same command with `--warmup 3`; the mean tracks the fully-cached shell path |
-| **First-post-apply latency** | Warm-shell parity — no cliff after `chezmoi apply` | Signals that regeneration lives outside the shell hot path | `chezmoi apply && hyperfine 'fish -i -c exit'` — cold and warm should be within noise |
-| **Cache-format compatibility** | Auto-heal path when upgrading between cache formats | Ensures long-lived workstations don't inherit stale caches on framework upgrade | Staleness check compares first line of cache to expected format marker |
-| **Bridge throughput** | ~40 µs per abbreviated entry, ~183 µs per aliased entry | Fish internals — measured, not documented | Choice of `abbr` over `alias` in the cache-emission format string |
-
-## Diagnosis: Where the Milliseconds Went #
-
-`fish --profile-startup=/tmp/f.prof -i -c 'exit'` emits a per-command trace with self-time and cumulative time. Sorted by cumulative time descending, one line dominated the warm-start budget:
-
-```
-Time (µs)  Sum (µs)  Command
-   1687    132211    ----> source "$_alias_cache"
-```
-
-**132 ms of a 231 ms budget** — 57% — spent sourcing a single cache file. Everything else (starship prompt initialisation, mise activation, atuin history bindings, direnv hooks) added up cleanly to the remaining ~85 ms.
-
-The cache file itself was well-formed and cache-invalidation was working correctly. The problem lived at the primitive level: what does `alias name='value'` cost when Fish parses and installs it? Ran in isolation:
-
-```
-$ hyperfine --warmup 2 "fish -c 'source ~/.cache/fish/bash-aliases.fish'"
-  Time (mean ± σ): 170.8 ms ± 11.3 ms
-```
-
-**170 ms just to source 878 alias lines.** Fish's `alias` isn't a shell-level string substitution — it's a function factory. The invocation `alias ll='eza -la --icons'` roughly desugars to:
-
-```fish
-function ll --wraps='eza -la --icons' --description 'alias ll=eza -la --icons'
-    eza -la --icons $argv
-end
-```
-
-Every call parses the definition, allocates a function object, installs it in the function table, records the description, and wires the `--wraps` for tab completion. Approximately 183 µs per entry. At 878 entries, the maths is uncompromising: 878 × 183 µs = 161 ms.
-
-The cost is O(1) per call, but the call count is the problem, and there is no batching path in Fish's `alias` implementation.
-
-## Remediation: `abbr --add` as a Cross-Shell-Bridge Primitive #
-
-Fish exposes two ways to give a short name to a longer command:
-
-- **`alias`** — function factory. Available in interactive shells, scripts, pipes, subshells, and inside other functions. Costs a function allocation on every source.
-- **`abbr --add`** — abbreviation. Expanded at the interactive command line the moment the user types the abbreviation and hits space or enter. Not available in scripts (they need functions). No function allocation on installation.
-
-For bash-alias bridges, the tradeoff is invisible: users don't call `ll` from inside a Fish script — they'd write a proper Fish function for that use case. Abbreviations for this workload are a strict upgrade: identical interactive UX, no function-table pressure, and — as a side benefit — they show the user what actually runs when they type the abbreviation, which improves shell literacy.
-
-The code change is a single printf format string in the cache-generator:
-
-```diff
--  printf "alias %s=%s\n" "$name" "$val"
-+  printf "abbr --add %s -- %s\n" "$name" "$val"
-```
-
-Measured in isolation:
-
-```
-Benchmark 1: fish -c 'source alias-cache.fish'
-  Time (mean ± σ):     170.8 ms ± 11.3 ms
-
-Benchmark 2: fish -c 'source abbr-cache.fish'
-  Time (mean ± σ):      34.0 ms ±  0.9 ms
-
-Summary
-  abbr-cache.fish ran 5.02 ± 0.36 times faster than alias-cache.fish
-```
-
-**5× faster. 137 ms saved on every warm shell start.** End-to-end Fish latency dropped from 231 ms → 119 ms.
-
-## The Second-Order Bug: Cache Invalidation Timing #
-
-Solving the warm case revealed a distinct failure mode: the *first* Fish shell opened after `chezmoi apply` still measured ~306 ms. The apply step writes new versions of the underlying bash alias source files (updated mtimes). The staleness check inside the Fish bridge sees `source.mtime > cache.mtime`, throws the cache away, and rebuilds it — spawning a subshell, sourcing 40 KB of bash, iterating 878 lines. **~200 ms.**
-
-The shell that pays this cost is whichever one the user opens first, which is almost always the shell they opened *because* they wanted to see the effect of the apply.
-
-The remediation is architectural, not algorithmic. The regeneration is moved off the interactive path and onto the apply itself via a chezmoi `run_onchange_after_` script:
-
-```bash
-#!/usr/bin/env bash
-# Source-hash retrigger keys — script re-runs when any of these change:
-#   90-ux-aliases.sh.tmpl:      {{ include "…/90-ux-aliases.sh.tmpl" | sha256sum }}
-#   91-ux-aliases-lazy.sh.tmpl: {{ include "…/91-ux-aliases-lazy.sh.tmpl" | sha256sum }}
-#   aliases.fish.tmpl:          {{ include "…/aliases.fish.tmpl" | sha256sum }}
-
-command -v fish >/dev/null 2>&1 || exit 0
-
-rm -f "${HOME}/.cache/fish/bash-aliases.fish"
-fish -i -c 'exit' >/dev/null 2>&1 || true
-```
-
-The hook invalidates the cache, spawns a throwaway interactive Fish so the bridge's existing regen path fires, then exits. The user's next actual shell finds a valid, up-to-date cache. The 200 ms cost lands where the user expects "compilation work" to happen — during the apply — not on the terminal they open ten seconds later.
-
-Cold-start Fish after apply: **306 ms → 120 ms.**
-
-## Return on Resilience #
-
-At a workstation opening 40 shells per day, saving 112 ms per shell reclaims 4.5 seconds daily; 22 minutes annually. At a small engineering org of 50 developers with the same profile, that's 18 engineering-hours reclaimed per year — measurable but modest.
-
-The stronger case is qualitative. Interactive-latency perception is nonlinear: at ~200 ms the user consciously notices lag; at ~120 ms the shell feels immediate. Once the felt lag is gone, the developer stops flinching before opening a terminal — which changes the frequency and length of exploratory shell work, which changes the shape of what they do at the CLI.
-
-| Metric | Before | After | Delta |
-|---|---|---|---|
-| Fish warm-start (median) | 231 ms | 119 ms | −112 ms (−48%) |
-| Fish cold-start after apply | 306 ms | 120 ms | −186 ms (−61%) |
-| Cache source cost | 170 ms | 34 ms | −136 ms (−80%) |
-| CI regression threshold | ✗ 231 > 200 | ✓ 119 ≤ 200 | Now under budget |
-| Full test suite | 4703 tests, 0 fail | 4703 tests, 0 fail | Zero regressions |
-
-## Takeaways #
-
-1. **Profile every interactive shell in CI.** Fish, Zsh, Nushell, Bash — each has its own primitives with different costs. Treat first-prompt latency as a signal with a threshold, not a comfort metric.
-
-2. **Prefer `abbr` for interactive-only bridged aliases in Fish.** The distinction between `abbr` (line-time expansion) and `alias` (function factory) is documented; the 5× cost distinction is not. If your users don't call the alias from inside a Fish script — and for bridged bash aliases they don't — `abbr` is a strict upgrade.
-
-3. **Move cache regeneration off the interactive path.** Any cache invalidated by a configuration-management action (chezmoi, ansible, dotbot) should be regenerated by that same action, not by whichever shell opens next.
-
-4. **Version the cache format itself, not just the source.** The staleness check should include a format marker so upgrading users don't inherit stale caches by mtime luck.
-
-The reference implementation lives on `main` at [sebastienrousseau/dotfiles](https://github.com/sebastienrousseau/dotfiles); the change landed as [PR #963](https://github.com/sebastienrousseau/dotfiles/pull/963) and [PR #964](https://github.com/sebastienrousseau/dotfiles/pull/964), shipped in [v0.2.510](https://github.com/sebastienrousseau/dotfiles/releases/tag/v0.2.510).