@sebastienrousseau/dotfiles 0.2.508 → 0.2.511

package/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 This file documents all notable changes to this project.
 
+## v0.2.511 — 2026-07-08
+
+Bug-fix release: restore shell aliases that were silently dropped after the CD-completion fragment.
+
+### Fixed
+
+- **`reload`, `r`, `mkcd`, `quit` — and every alias/function defined after the CD-completion block — were undefined** whenever `compdef` was not yet available when `90-ux-aliases.sh` was sourced (profiles that don't run `compinit`, and fast-startup shells). The zsh branch of `defaults/.chezmoitemplates/aliases/cd/cd-completion.aliases.sh` skipped completion registration with a **file-scope `return 0`**; because that fragment is inlined into the single concatenated `90-ux-aliases.sh`, the bare `return` aborted the whole file, dropping `set_default_aliases()` (which defines `reload` et al.) and everything after it. Replaced the early-return with a positive `if command -v compdef …; then … fi` guard, so only the completion block is skipped when `compdef` is not ready.
+
+### Changed
+
+- **`scripts/version-sync.sh`**: excluded the two dated release write-ups (`docs/articles/2026-07-05-*.md`) from version verification. They record the release they shipped in ("shipped in v0.2.510" + release-tag link) as historical fact; the `--verify` pass was false-flagging those refs as inconsistent even though the update pass correctly leaves them alone.
+
+## v0.2.510 — 2026-07-05
+
+Post-v0.2.509 quality-of-life release: default branch renamed `master` → `main`, docs site relit with a custom dark + terminal-green MkDocs Material theme, shells warmed up (fish alias→abbr, zsh PATH prune), font bumped to 20pt across every terminal template, themes rebuilt from wallpapers.
+
+### Added
+
+- **Custom docs theme** (#960). doc.dotfiles.io now serves MkDocs Material with a bespoke palette (near-black `#0b0e14` background, terminal-green `#7ee787` accent), Inter + JetBrains Mono fonts, hero + 8-card feature grid landing page. Header, tabs, sidebar, TOC, admonitions, code blocks, tables, custom scrollbar all restyled in `docs/stylesheets/extra.css`.
+- **CLAUDE.md `## Handing over commands` rule** (#959). Cross-project preference deployed to `~/.claude/CLAUDE.md`: when Claude Code needs the user to run shell steps themselves, it must hand them over as one runnable script file, not fenced code blocks or scattered one-liners.
+- **`mirror-main-to-master` workflow** (#961). Fast-forwards `master` from `main` on every push during the rename grace period so bookmarked `raw.githubusercontent.com/…/master/…` install URLs keep resolving. Retire on 2027-07-05 per tracking issue #962.
+- **fish alias-cache pre-warm** (#964). New `run_onchange_after_30-regen-fish-alias-cache.sh.tmpl` regenerates `~/.cache/fish/bash-aliases.fish` at chezmoi-apply time when the alias sources change, so the first fish shell after apply doesn't pay ~200ms rebuilding the cache from scratch.
+
+### Changed
+
+- **Default branch: `master` → `main`** (#961). GitHub-side rename plus 96 in-repo edits (workflow triggers, docs URIs, install URLs, ruleset filename, git aliases). Every `raw.githubusercontent.com/…/master/…` and `github.com/…/blob/master/…` reference now points at `/main/`. Workflow `pull_request:` / `push:` triggers keep `master` as a grace-period fallback until the mirror is retired.
+- **Portability + missing commands** (#953). Ships as part of v0.2.509 via PR #953 (already tagged) — cross-platform fixes for macOS/BSD/Alpine/openSUSE (base64 `-D` fallback, `sort -V` stdin buffering, `date +%s%3N` guards, zypper/apk/pkg package-manager detection) plus wiring for `dot teleport`, `dot uninstall`, `dot policy`, `dot secret-audit`, `dot completion <bash|zsh|fish|nu>`, `dot fonts patch`. Cross-shell parity for `dot secrets load --shell posix|fish|nu` and auto-secret-load in bash/fish/nushell. See [v0.2.509 release notes](https://github.com/sebastienrousseau/dotfiles/releases/tag/v0.2.509).
+- **Terminal font 12 → 20** (#963). `defaults/.chezmoidata.toml` and every terminal template (alacritty, wezterm, ghostty, kitty, waybar) bumped so a fresh install reads at 20pt across the surface.
+- **Themes rebuilt** (#963). K-Means CIELAB color extraction re-run over all 206 detected wallpapers → 752 theme sections. Five dark themes removed where the underlying wallpaper is inherently light-toned (hello, iphone, valentine, modern, firewatch) — their `-light` counterparts kept.
+- **Zsh PATH prune** (#963). The pre-existing dedup+prune tail in `00-core-paths.sh` was gated behind `[ -z "$ZSH_VERSION" ]`, so zsh never pruned. Now runs native zsh path-array iteration for zsh (89 → 77 entries with no non-existent dirs) alongside the existing bash 4+ associative-array and bash 3.x awk paths.
+
+### Fixed
+
+- **Fish startup 217 ms → 119 ms** (#963). `defaults/dot_config/fish/conf.d/aliases.fish.tmpl` now writes the bash-bridge cache as `abbr --add NAME -- VALUE` instead of `alias NAME=VALUE`. Fish's `alias` builtin creates one function per entry (~183 µs); `abbr` is a command-line-time expansion at ~40 µs. Sourcing the same 878-entry cache went 170 ms → 34 ms. Cache self-heals on upgrade (staleness now also fires on the old `alias` format).
+- **Scorecard code-scanning alerts** (this release, #965). Nine `TokenPermissionsID` alerts closed by adding top-level `permissions: contents: read` (least-privilege default) to workflows that only declared job-level write permissions. One `PinnedDependenciesID` alert closed by hash-locking `requirements-docs.txt` via `pip-compile --generate-hashes` and switching pages.yml to `pip install --require-hashes`.
+
+### Housekeeping
+
+- Bumped `package.json`, `defaults/.chezmoidata.toml`, and every managed markdown reference from `v0.2.508` → `v0.2.510` (26 files consistent).
+- Pruned the stale `feat/v0.2.509` local branch (its remote was deleted at merge time).
+- Retired the `.git/*.sh` session helper scripts left over from the rename + docs-theme + housekeeping PRs.
+
 ## v0.2.508 — 2026-06-30
 
 Makes `dot apply` / `dot update` behave like an OS package-manager update —

package/README.md

@@ -10,7 +10,7 @@
 
 <p align="center">
   <a href="https://github.com/sebastienrousseau/dotfiles/actions"><img src="https://img.shields.io/github/actions/workflow/status/sebastienrousseau/dotfiles/ci.yml?style=for-the-badge&logo=githubactions&logoColor=white" alt="Build" /></a>
-  <a href="https://github.com/sebastienrousseau/dotfiles/releases/latest"><img src="https://img.shields.io/badge/Version-v0.2.508-blue?style=for-the-badge&logo=semanticrelease&logoColor=white" alt="Version" /></a>
+  <a href="https://github.com/sebastienrousseau/dotfiles/releases/latest"><img src="https://img.shields.io/badge/Version-v0.2.511-blue?style=for-the-badge&logo=semanticrelease&logoColor=white" alt="Version" /></a>
   <a href="https://github.com/sebastienrousseau/dotfiles/releases"><img src="https://img.shields.io/github/downloads/sebastienrousseau/dotfiles/total?style=for-the-badge&logo=github&logoColor=white" alt="Downloads" /></a>
   <a href="https://codespaces.new/sebastienrousseau/dotfiles"><img src="https://img.shields.io/badge/Open%20in-Codespaces-blue?style=for-the-badge&logo=github&logoColor=white" alt="Open in GitHub Codespaces" /></a>
   <a href="https://scorecard.dev/viewer/?uri=github.com/sebastienrousseau/dotfiles"><img src="https://img.shields.io/ossf-scorecard/github.com/sebastienrousseau/dotfiles?style=for-the-badge&logo=linuxfoundation&logoColor=white&label=OpenSSF%20Scorecard" alt="OpenSSF Scorecard" /></a>
@@ -30,7 +30,7 @@
          --idle-time-limit 1 --rows 30 --cols 100 \
          --title "Dotfiles: install → doctor → theme"
        # in the recording shell:
-       #   curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh | bash
+       #   curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh | bash
        #   dot doctor
        #   dot theme rebuild --force
        # then Ctrl-D to stop
@@ -52,7 +52,7 @@
 
 ```bash
 curl -fsSL -o /tmp/dotfiles-install.sh \
-  https://raw.githubusercontent.com/sebastienrousseau/dotfiles/v0.2.508/install.sh
+  https://raw.githubusercontent.com/sebastienrousseau/dotfiles/v0.2.511/install.sh
 echo "d5a04c5e2813a93a63c8ecce9655cf3d107f6068862c6eba84a92cf22f801c7e  /tmp/dotfiles-install.sh" \
   | shasum -a 256 -c
 bash /tmp/dotfiles-install.sh
@@ -61,7 +61,7 @@ bash /tmp/dotfiles-install.sh
 **Trust-source one-liner** (skips the SHA check — fine for sandboxes and ephemeral CI, not recommended for primary workstations):
 
 ```bash
-bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh)"
+bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh)"
 ```
 
 Then verify and explore:
@@ -80,7 +80,7 @@ Silent install (no prompts):
 
 ```bash
 DOTFILES_SILENT=1 DOTFILES_NONINTERACTIVE=1 \
-  bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh)"
+  bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh)"
 ```
 
 Docker sandbox:

package/docs/COPYRIGHT

@@ -1,5 +1,5 @@
 /*
-* 🅳🅾🆃🅵🅸🅻🅴🆂 (v0.2.508) - <https://github.com/sebastienrousseau/dotfiles>
+* 🅳🅾🆃🅵🅸🅻🅴🆂 (v0.2.511) - <https://github.com/sebastienrousseau/dotfiles>
 * Made With ❤️ in London, United Kingdom
 * Designed by
 * Copyright (c) 2015-2026. All rights reserved.

package/docs/GOVERNANCE.md

@@ -22,7 +22,7 @@ exist.
 ## Contribution flow
 
 1. **Issue** for non-trivial work. Confirm scope before coding.
-2. **Branch** off `master`: `feat/<scope>`, `fix/<scope>`,
+2. **Branch** off `main`: `feat/<scope>`, `fix/<scope>`,
    `docs/<scope>`, etc.
 3. **PR** with description following the template:
    - Summary (1–3 bullets)
@@ -51,7 +51,7 @@ For breaking changes or substantial new features:
    - **Backwards compatibility** (what breaks, migration path)
    - **Alternatives considered** (with reasons rejected)
    - **Unresolved questions**
-2. Open a PR labelled `rfc` against `master`.
+2. Open a PR labelled `rfc` against `main`.
 3. Comment window: 14 days minimum.
 4. Maintainer renders a decision (accept / accept-with-changes /
    reject) with public reasoning in the PR.

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

@@ -137,8 +137,8 @@ plugin system, bash bridge for aliases) await an actual user request.
 
 ## References
 
-- [`dot_config/nushell/cached_eval.nu`](../../defaults/dot_config/nushell/cached_eval.nu) — the new module.
-- [`dot_config/nushell/env.nu.tmpl`](../../defaults/dot_config/nushell/env.nu.tmpl) — adopter.
+- [`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/articles/.pages

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

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

@@ -0,0 +1,153 @@
+---
+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).