@sebastienrousseau/dotfiles 0.2.510 → 0.2.512

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).

package/docs/articles/2026-07-05-master-to-main-rename-runbook.md

@@ -0,0 +1,128 @@
+---
+title: "Renaming master to main in 2026: A Zero-Downtime Runbook"
+description: A supply-chain-safe procedure for renaming the default branch of a mature open-source repository — 96 in-repo edits, a grace-period mirror workflow, zero broken install URLs.
+date: 2026-07-05
+---
+
+# Renaming `master` to `main` in 2026: A Zero-Downtime Runbook for a Repository at the Heart of an Open-Source Supply Chain
+
+*Renaming the default branch of a mature repository is a supply-chain event, not a cosmetic one; done wrong, it strands `curl \| bash` install commands, breaks CI, and severs external distribution channels.*
+
+*Sebastien Rousseau · Published 5 Jul 2026 · 12 min read*
+
+## Why Default-Branch Naming Matters in 2026 #
+
+Every open-source project with a public install path publishes a URL of the form `raw.githubusercontent.com/<owner>/<repo>/<branch>/install.sh`. Every downstream consumer who has copied that URL — into a README, a Slack message, a devcontainer, a company wiki, a StackOverflow answer, a Homebrew tap, an AUR PKGBUILD, an internal Ansible playbook — has taken an implicit dependency on that branch name. Renaming the branch is a **breaking change to the project's public API surface**, whether the maintainer intended one or not.
+
+The industry moved off `master` as the default branch name years ago; new repositories default to `main`. Existing repositories, however, live with a naming inconsistency that becomes actively confusing when a maintainer has multiple projects — some on `main`, some still on `master`. The migration is unavoidable, but the operational risk profile is significant enough that most maintainers put it off indefinitely.
+
+This article documents the migration of the [.dotfiles](https://github.com/sebastienrousseau/dotfiles) repository — 60+ files with hardcoded branch references, four external distribution channels, three CI providers tracking the default branch, and a public install command bookmarked by an unknown number of downstream users. The migration was **zero-downtime**: no install command broke, no CI job failed, no downstream integration degraded. The blueprint is generalisable to any medium-complexity open-source repository.
+
+## The Branch-Rename 2026 Architecture Lens #
+
+A default-branch rename is not a single operation. It's a sequence of coordinated changes across a defined dependency graph, each with its own migration mechanism:
+
+| Layer | Design Decision | Why It Matters | Risk if Mishandled |
+|---|---|---|---|
+| **GitHub metadata** | Native rename via Settings → Branches or `POST /repos/{owner}/{repo}/branches/{branch}/rename` | GitHub auto-migrates default-branch setting, open PR targets, branch-protection assignment, ruleset targeting, and Pages source | Renaming via manual `git push :old-name` + `git push new-name` skips the auto-migration and orphans PRs |
+| **In-repo workflow triggers** | `.github/workflows/*.yml` `branches:` lists updated pre-rename | Workflows that trigger on `push:` or `pull_request:` targeting the old name silently stop firing after rename | Migration PR itself under-tested — the workflows it edits no longer fire on it |
+| **Grace-period mirror** | New workflow fast-forwards `master` from `main` on every push | Preserves `raw.githubusercontent.com/…/master/…` URLs for downstream consumers who cannot be reached | External `curl \| bash` install commands return HTTP 404 the moment `master` ceases to exist |
+| **Documentation URIs** | `mkdocs.yml` `edit_uri`, README install commands, docs prose | GitHub redirects `github.com/…/blob/master/…` automatically; `raw.githubusercontent.com/…/master/…` does **not** redirect | Docs site edit buttons point at nonexistent branches; install commands 404 |
+| **Rulesets as code** | `.github/rulesets/<branch>.json` file renamed alongside the JSON `target.include` | Machine-readable ruleset files that reference `refs/heads/master` misalign with GitHub's auto-migrated state | Configuration drift between the in-repo policy source of truth and GitHub's live enforcement |
+| **Test-suite assertions** | Regression tests that asserted `/master/` URLs in README updated to assert `/main/` | Tests written before rename fail *after* rename in the exact commit that fixes them | Migration PR shows red CI, blocking merge |
+| **External distribution** | Homebrew tap, Scoop bucket, AUR PKGBUILD — pinned to release tags, not branches | Version-pinning insulates external distribution from branch renames | Branch-pinned distribution manifests break silently on rename |
+
+## Key Branch-Rename Migration Signals #
+
+| Signal | Operational Benchmark | Reference | Technical Platform Implementation |
+|---|---|---|---|
+| **URL Reachability Post-Rename** | `HTTP 200` on both `main/install.sh` and `master/install.sh` for the full grace period | External-consumer continuity | Mirror workflow: `on: push: branches: [main]` → `git push origin main:refs/heads/master` |
+| **CI Coverage on Migration PR** | Workflow-trigger `branches:` list transitionally includes both `main` and `master` | Migration PR must be tested against the current default | `pull_request: branches: [main, master]` — remove `master` once the mirror retires |
+| **In-Repo URL Consistency** | Zero remaining `/master/` URIs on the head branch, excluding intentional mirror-preservation strings | Doc/install correctness | `git grep 'raw.githubusercontent.com/.../master/'` returns empty (or only test-fixture strings) |
+| **Ruleset File Alignment** | `.github/rulesets/*.json` filename matches its `target.include` refspec | Config-as-code hygiene | File rename via `git mv` + JSON `target.include` update in the same commit |
+| **Grace-Period Retirement Marker** | Calendar-visible tracking item with an explicit sunset date | Operational-debt visibility | GitHub issue with target date in title + calendar event (`.ics` or Google Calendar quick-add URL) |
+
+## Diagnosis: Enumerating the Blast Radius #
+
+Before touching a single file, an authoritative audit surfaces the full inventory of `master` references. On the .dotfiles repository, that surfaced **~88 mechanical replacements across 60 files**, grouped as:
+
+- **24 GitHub Actions workflow files** — trigger lists, `github.ref_name == 'master'` conditionals, `--base master` PR-creating steps, inline `@SHA # master` comments describing what commit was pinned
+- **7 `raw.githubusercontent.com/.../master/…` URLs** — README install command, `install.sh` (referencing itself in its own comment header), `bin/dot-bootstrap`, `docs/index.md`, install guide, MkDocs edit_uri, chezmoi-data JSON `$id` field
+- **~25 documentation files** — `github.com/…/blob/master/…` references in operations runbooks, security docs, architecture decision records
+- **1 ruleset-as-code file** — `.github/rulesets/master.json` with a `target.include: refs/heads/master` field
+- **1 regression test** — asserting the README contains `/master/` (a red-team catch: this test PROTECTS against accidental rename, which now needs its assertion inverted)
+- **4 legitimately-kept references** — the `gbd` bulk-branch-delete script with a `main|master` whitelist regex, the `git-primary-branch` shell function's fallback path, the release-branch check in `scripts/ops/release.sh`, and Scorecard-linter fixtures demonstrating `@master` as an anti-pattern
+
+## Remediation Sequence #
+
+The rename is executed as a five-phase sequence, each with a distinct commit or GitHub operation:
+
+**Phase 1 — Pre-migration content preparation.** A single pull request rewrites all in-repo `master` references while `master` is still the default branch. This PR must merge before any GitHub-side rename. Workflow `pull_request:` triggers gain `[main, master]` (paired) so the PR itself triggers CI against the current default. The ruleset file is renamed via `git mv` and its JSON target updated. The regression test's assertion is inverted from "must contain `/master/`" to "must contain `/main/`".
+
+**Phase 2 — GitHub-side rename.** Via UI (`Settings → Branches → Rename`) or API (`POST /repos/{owner}/{repo}/branches/master/rename`). GitHub auto-migrates default-branch setting, PR targets, branch-protection assignment, ruleset targeting, Pages source. Blocked if a branch-protection *rule pattern* targeting the new name already exists — delete the empty rule first via GraphQL:
+
+```
+gh api graphql -f query='
+mutation {
+  deleteBranchProtectionRule(input: { branchProtectionRuleId: "..." }) {
+    clientMutationId
+  }
+}'
+```
+
+**Phase 3 — Mirror workflow activation.** Trigger the pre-committed mirror workflow via `workflow_dispatch` or a small push to `main`. The workflow performs a fast-forward `git push origin main:refs/heads/master`, recreating `master` as a passive mirror. From this point forward, every push to `main` mirrors automatically.
+
+**Phase 4 — Local clone update (per-workstation).** Every developer with an active clone runs:
+
+```
+git branch -m master main
+git fetch origin
+git branch -u origin/main main
+git remote set-head origin -a
+```
+
+**Phase 5 — Retirement scheduling.** A GitHub issue with a title-embedded target date (`[2027-07-05] Retire master mirror + tighten workflow triggers to main-only`) plus a calendar reminder ensures the grace-period mirror doesn't become permanent operational debt.
+
+## Verification: URLs, CI, Docs Site #
+
+Post-rename smoke tests:
+
+```
+$ curl -sI https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh   | head -1
+HTTP/2 200
+$ curl -sI https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh | head -1
+HTTP/2 200
+```
+
+Both branch names resolve during the grace period. When the mirror is retired in 12 months, `/master/` returns 404 by design — but by then no active install command should still reference it.
+
+CI status post-rename: on the .dotfiles repository, the migration PR (`#961`) ran **70 checks green, 0 failed**, driven by the `[main, master]` trigger-list transitional configuration. The follow-up test-coverage PR (`#963`) confirmed no downstream test regression.
+
+Docs site: MkDocs `edit_uri` — updated from `edit/master/docs/` to `edit/main/docs/` — resolves correctly. `github.com/…/blob/master/…` links continue to work via GitHub's built-in redirect; `raw.githubusercontent.com/…/master/…` works via the mirror.
+
+## Return on Resilience #
+
+The commercial value of a supply-chain-safe rename is defensive, not offensive: nothing new is built, but nothing existing breaks.
+
+| Metric | Result |
+|---|---|
+| Files updated in migration PR | 97 (96 edits + 1 rename + 1 new workflow) |
+| Grace-period external URL uptime | 100% (both `/main/` and `/master/` return HTTP 200) |
+| CI checks post-rename | 70 green, 0 failed |
+| Downstream distribution channels broken | 0 (Homebrew tap, Scoop bucket, AUR pinned to tags) |
+| Local-clone update commands | 4 lines, ~5 seconds per workstation |
+| Operational debt introduced | 1 mirror workflow, retired via calendar-scheduled task 2027-07-05 |
+
+## Takeaways #
+
+1. **Land the in-repo edits before the GitHub-side rename.** Merging Phase 1 while `master` is still default gives you both a working CI baseline and a rehearsal.
+
+2. **Add the mirror workflow before renaming, not after.** The interval between the GitHub rename and the mirror's first fast-forward push is the window during which `raw.githubusercontent.com/…/master/…` returns 404. Minimising that window is a matter of ordering.
+
+3. **Update `pull_request:` triggers transitionally.** `branches: [main, master]` covers the migration PR itself (which targets the pre-rename default) and every future PR (which will target `main`). The grace-period `master` entry retires with the mirror.
+
+4. **Track retirement as an issue with an explicit sunset date.** Mirror workflows are the classic case of "temporary" becoming "permanent". A calendar event and a GitHub issue with a date-anchored title enforce end-of-life.
+
+5. **Rulesets-as-code files must be renamed alongside their JSON targets.** GitHub auto-migrates the *live* ruleset assignment; the file in your repo is the source-of-truth if you ever reapply. Both must agree.
+
+The reference implementation landed as [PR #961](https://github.com/sebastienrousseau/dotfiles/pull/961) with the retirement issue tracked at [#962](https://github.com/sebastienrousseau/dotfiles/issues/962), shipped in [v0.2.510](https://github.com/sebastienrousseau/dotfiles/releases/tag/v0.2.510).

package/docs/articles/index.md

@@ -0,0 +1,36 @@
+---
+title: Articles
+description: Long-form writing on the design and operation of the .dotfiles framework.
+---
+
+# Articles
+
+Long-form writing on the design and operation of the [.dotfiles framework](https://github.com/sebastienrousseau/dotfiles) — deep dives into performance, supply-chain safety, developer experience, and the architectural decisions that shape a mature open-source dotfiles project.
+
+<div class="grid cards" markdown>
+
+- :material-console:{ .lg .middle } **[Fish Startup in 2026](2026-07-05-fish-startup-abbr.md)**
+
+    ---
+
+    Cutting interactive shell latency by 48% with `abbr` on multi-shell dotfiles. One printf format change + one chezmoi hook = 112 ms saved per fresh terminal.
+
+    *5 Jul 2026 · 10 min read*
+
+- :material-source-branch:{ .lg .middle } **[Renaming `master` to `main`](2026-07-05-master-to-main-rename-runbook.md)**
+
+    ---
+
+    A zero-downtime runbook for a repository at the heart of an open-source supply chain. 96 in-repo edits, a 12-month mirror workflow, zero broken install URLs.
+
+    *5 Jul 2026 · 12 min read*
+
+- :material-palette:{ .lg .middle } **[Custom Documentation Sites in 2026](2026-07-05-custom-mkdocs-material-dark-theme.md)**
+
+    ---
+
+    Building a distinctive dark-themed developer reference on MkDocs Material — three files, no theme forking, WCAG AAA contrast, hash-locked build.
+
+    *5 Jul 2026 · 11 min read*
+
+</div>

package/docs/manual/00-introduction.md

@@ -4,7 +4,7 @@ render_with_liquid: false
 
 # Introduction
 
-This manual describes `.dotfiles` v0.2.510 — a trusted agent workstation baseline for macOS, Linux, and WSL.
+This manual describes `.dotfiles` v0.2.512 — a trusted agent workstation baseline for macOS, Linux, and WSL.
 
 The repository is more than a personal dotfiles collection. It ships as workstation infrastructure: signed, attested, multi-platform, AI-aware, and self-healing. Chezmoi handles templating and platform differences. The `dot` CLI sits on top and coordinates lifecycle operations.
 

package/docs/manual/02-tutorials/02-add-wallpaper.md

@@ -126,10 +126,10 @@ Output:
 ```
 NAME                        SOURCE     PATH
 ----                        ------     ----
-big-sur-graphic-dark        system     /System/Library/Desktop Pictures/.thumbnails/Big Sur Graphic Dark.heic
-big-sur-graphic-light       system     /System/Library/Desktop Pictures/.thumbnails/Big Sur Graphic Light.heic
-dome-dark                   system     /System/Library/Desktop Pictures/.thumbnails/Dome Dark.heic
-dome-light                  system     /System/Library/Desktop Pictures/.thumbnails/Dome Light.heic
+monterey-dark               system     /System/Library/Desktop Pictures/.thumbnails/Monterey Dark.heic
+monterey-light              system     /System/Library/Desktop Pictures/.thumbnails/Monterey Light.heic
+tahoe-dark                  system     /System/Library/Desktop Pictures/.thumbnails/Tahoe Dark.heic
+tahoe-light                 system     /System/Library/Desktop Pictures/.thumbnails/Tahoe Light.heic
 sonoma-dark                 system     /System/Library/Desktop Pictures/.thumbnails/Sonoma Dark.heic
 ...
 Total: 152 wallpapers
@@ -138,10 +138,10 @@ Total: 152 wallpapers
 Switch to any system wallpaper:
 
 ```sh
-dot theme dome-dark
+dot theme monterey-dark
 ```
 
-The engine extracts Dome Dark's dominant colors, generates a palette, and applies it to every surface.
+The engine extracts Monterey Dark's dominant colors, generates a palette, and applies it to every surface.
 
 ## Verifying the Result
 

package/docs/manual/02-tutorials/03-create-profile.md

@@ -48,7 +48,7 @@ Edit `~/.config/chezmoi/chezmoi.toml`:
 ```toml
 [data]
 machine = "surface-pro"      # choose from .chezmoidata/hardware.toml
-theme = "dome-dark"
+theme = "monterey-dark"
 default_shell = "fish"
 terminal_font_family = "JetBrainsMono Nerd Font"
 terminal_font_size = 11       # larger for HiDPI, smaller for dense screens

package/docs/manual/02-tutorials/05-deploy-fleet.md

@@ -146,7 +146,7 @@ Each host has its own `~/.config/chezmoi/chezmoi.toml` — use it for things tha
 # surface-pro's chezmoi.toml
 [data]
 machine = "surface-pro"
-theme = "dome-dark"           # per-host default
+theme = "monterey-dark"       # per-host default
 default_shell = "fish"
 terminal_font_size = 11       # smaller for HiDPI
 ```

package/docs/manual/03-reference/02-config-files.md

@@ -122,7 +122,7 @@ sourceDir = "/Users/you/.dotfiles"
 
 [data]
 machine = "surface-pro"      # selects preset from hardware.toml
-theme = "dome-dark"          # overrides .chezmoidata.toml default
+theme = "monterey-dark"      # overrides .chezmoidata.toml default
 default_shell = "fish"
 terminal_font_size = 11
 email = "you@example.com"

package/docs/manual/command-index.md

@@ -77,6 +77,7 @@ job `lint/command-index` fails when this file is stale.
 | `dot history` | Shell history analysis |
 | `dot keys` | Keybindings (sign-check: verify git signing) |
 | `dot keys` | sign-check Verify git commit-signing configuration and key availability |
+| `dot kimi` | Kimi CLI with context patterns |
 | `dot kiro` | Kiro CLI with context patterns |
 | `dot learn` | Start the interactive tour of your new tools |
 | `dot lint` | Lint shell scripts (--fix |

package/docs/operations/ARCHITECTURE_ROADMAP.md

@@ -1,145 +1,7 @@
----
-title: "Architecture & Roadmap — cross-shell consistency, performance, decoupling"
-date: 2026-07-01
-status: living document
----
+# Architecture Roadmap
 
-# Architecture & Roadmap
+Historical architecture planning has been consolidated into the canonical
+[`../../ROADMAP.md`](../../ROADMAP.md).
 
-This document captures a deep-dive across four fronts — cross-shell
-consistency, real startup performance, the 2026 competitive/research
-landscape, and a plan to decouple optional subsystems (`dot ai`, MCP, LSP)
-into companion repos around a stable core. It is the source of truth for
-the multi-phase program tracked below.
-
-> Honesty policy: every performance number here is **measured** with
-> `hyperfine` (warmed up), reproducible with the harness in
-> `tests/performance/bench.sh` (interactive sessions, all installed shells)
-> and `dot benchmark`. Estimates are labelled as such. The
-> built-in `dot doctor` perf readout historically **understated** real
-> startup because it timed a narrower slice — Phase 0 reconciles that.
-
-## 1. Measured performance baseline (2026-07-01, Apple Silicon)
-
-Method: `hyperfine -N --warmup 5` on the deployed config; `exit`-on-launch.
-
-| Shell   | Startup (mean) | rc cost over ~7ms spawn | vs <30ms target |
-|---------|----------------|-------------------------|-----------------|
-| nushell | 24.8 ms        | —                       | meets           |
-| bash    | 51.1 ms        | +43.6 ms                | 1.7× over       |
-| zsh     | 66.3 ms        | +59.6 ms                | 2.2× over       |
-| fish    | 128.8 ms       | bash-bridge tax         | 4.3× over       |
-
-Baselines (pure process spawn, no rc): `zsh -fc exit` 6.7 ms,
-`bash --norc` 7.5 ms.
-
-Cost attribution (uncached tool-init subprocess cost, what `_cached_eval`
-caches away): `mise activate` 17.7 ms, `atuin init` 7.1 ms,
-`starship init` 4.0 ms, `zoxide init` 2.4 ms. `_cached_eval` **is**
-working (cache files fresh; `zcompdump` is `zcompile`d), which is why zsh
-is 66 ms and not ~97 ms.
-
-**<30ms verdict (honest):** not reachable for the *full eager stack*
-(mise + starship + atuin + zoxide + fzf + zinit + ~97 alias files + ~53
-functions + compinit) on zsh/bash without tradeoffs. It **is** reachable
-as a tunable "fast profile" + first-prompt deferral. nushell already
-meets it; fish (bash-bridge) is the worst and the biggest opportunity.
-
-## 2. Cross-shell consistency
-
-- bash/zsh are native + single-source; **fish and nushell are bash
-  *bridges*** — they filter aliases and wrap functions via `bash -c`
-  subshells, adding a runtime bash dependency and silent parity loss.
-- Parity gap: bash/zsh ~53 functions; fish 27 native; nushell 0 native;
-  ~26 functions have no native impl; behaviour drifts (e.g. `goto` loses
-  directory grouping in fish/nu).
-- Duplication: eza-detection logic in bash + 7 fish files + nu wrappers;
-  `_cached_eval` reimplemented four times.
-- Direction: a **manifest-driven single source of truth** (one
-  alias/function spec → per-shell generators). This also removes the
-  class of parse-time collision that produced the zsh alias-shim bug.
-
-## 3. Decoupling architecture
-
-```
-                     dotfiles (CORE)
-   dot CLI · lib/dot/ui.sh · utils.sh · chezmoi base · plugin API
-        |               |                 |             |
-   dotfiles-ai     dotfiles-mcp      dotfiles-lsp    (future)
-   dot ai,          registry,         dot/alias/
-   cockpit,         policy,           chezmoi-template
-   gateway          mcp-doctor        completions
-```
-
-Readiness (from the coupling audit):
-
-| Subsystem | Coupling | Effort | Notes |
-|-----------|----------|--------|-------|
-| MCP | low (declarative JSON + one `cmd_mcp`) | low | isolated by design |
-| LSP | none (one nvim plugin file) | trivial | already a lazy.nvim plugin |
-| `dot ai` | high (ui.sh, utils.sh, dispatcher, chezmoi hooks) | high | needs the two contracts below |
-
-Two foundational contracts must exist before AI can move cleanly:
-
-1. **Extract `lib/dot/ui.sh` into a versioned shared lib** — AI *and* MCP
-   depend on it; without this, decoupling means duplication.
-2. **A `dot` plugin/extension API** — manifest-registered subcommands so
-   companion repos add `dot ai` / `dot mcp` without forking the
-   dispatcher.
-
-## 4. 2026 landscape — gaps worth adopting (highest value first)
-
-- **`dotfiles-mcp` with a secrets-redaction + allowlist policy layer** — a
-  genuine gap no existing dotfiles-MCP fills; reuses the gitleaks / Atuin
-  `history_filter` posture. Expose introspection via MCP **Resources**,
-  actions via **Tools**.
-- **`dotfiles-lsp`** = `dot` subcommand completions + alias awareness +
-  **chezmoi-template-data-aware** completions → a novel *combination*
-  (weekend-scale MVP using just-lsp / tcl-lsp patterns).
-- Password-manager templating (1Password/Bitwarden), SOPS for shared
-  secrets, **Bats** tests (reviewer lingua franca), devcontainer/Codespaces
-  fast install path.
-
-Context: chezmoi has won the dotfiles category; mise is baseline; Starship
-has overtaken Powerlevel10k (maintenance-only); MCP spec 2025-11-25 is
-under the Linux Foundation and safe to build on.
-
-## 5. Staged roadmap
-
-Each phase ships as its own reviewed PR with before/after benchmarks.
-
-| Phase | Work | Risk | Target payoff |
-|-------|------|------|---------------|
-| **0** | Honest benchmark harness in-repo; make `dot doctor` report real numbers | low | truth in metrics |
-| **1** | Perf quick-wins audit (deferral, compinit, zcompile, mise ordering) | low | verify + record baseline |
-| **2** | Extract `lib/dot/ui.sh` → versioned shared lib | med | unblocks decoupling |
-| **3** | `dot` plugin API + carve out `dotfiles-mcp` (lowest-risk repo) | med | proves the model |
-| **4** | Cross-shell manifest (single source → per-shell generators); de-bash-bridge fish | high | consistency + fish speed |
-| **5** | `dotfiles-ai` as a plugin repo | high | the decoupling goal |
-| **6** | `dotfiles-lsp` MVP | low | differentiation |
-| **7** | Docs + `examples/` + published honest benchmarks | med | completeness |
-
-### Status
-
-- **Phase 0 — done** (`feat/v0.2.509`): `tests/performance/bench.sh` now times
-  every shell *interactively* (fish was measured non-interactively, faking
-  ~12ms vs the real ~118ms) and includes nushell; `dot doctor` reports the
-  real medians.
-- **Phase 1 — done (audit)** (`feat/v0.2.509`): the documented quick-wins are
-  **already implemented** in the deployed config, verified:
-  - `compinit` deferred to first prompt, `-C` + daily-audit cache
-    (`~/.config/zsh/rc.d/30-options.zsh`).
-  - Eagerly-sourced hub files are `zcompile`d (`.zwc` present).
-  - Plugins turbo-deferred (`zinit ice wait lucid`), fzf backgrounded, and
-    mise/atuin/starship/zoxide inits deferred to post-prompt hydration and
-    cached via `_cached_eval`.
-  - `mise activate` ordering is a non-issue here: zsh uses `add-zsh-hook`
-    (appends, no overwrite) and bash manages `PROMPT_COMMAND` explicitly.
-  - Net: `zsh -ic exit` (which runs before the prompt, so it excludes the
-    deferred inits) is ~66ms of *eager* rc — dominated by sourcing the large
-    aggregated alias/function hubs. No safe further quick-win remains.
-  - **Consequence:** sub-30ms is not reachable by tuning; it needs Phase 4
-    (manifest → cut the eager alias/function volume) or a lean profile.
-    fish (~118ms) is the biggest single opportunity (bash-bridge), also
-    Phase 4.
-- Phases 2–7 — planned; sequencing subject to review.
+Current architecture decisions belong in `docs/architecture/`; future roadmap
+items belong in the root roadmap or in GitHub issues and milestones.

package/docs/operations/COVERAGE.md

@@ -43,17 +43,40 @@ matches and emits standard `lcov.info` that Codecov ingests natively.
 
 | Surface | What runs |
 |---|---|
-| **PR + push to main** | `.github/workflows/coverage.yml` → `Coverage / kcov` job → uploads lcov.info to Codecov and fails the build below `MIN_COVERAGE_PCT` (currently `0`, ratcheted up each slice). |
+| **PR + push to main** | `.github/workflows/coverage.yml` → `Coverage / kcov` job → uploads lcov.info to Codecov and fails the build below `MIN_COVERAGE_PCT` (currently `49`, ratcheted up after measured integer-floor gains). |
 | **Local dev** | `bash tools/ci/run-coverage.sh` — works on Linux + macOS (xtrace is a bash primitive, no platform tools needed). |
-| **macOS dev** | Supported. xtrace-based instrumentation runs on macOS bash 3.2+ and Homebrew bash 5.x. |
+| **macOS dev** | Supported. xtrace-based instrumentation runs on macOS bash 3.2+ and Homebrew bash 5.x, with a Perl alarm fallback when GNU `timeout`/`gtimeout` is unavailable. |
 
 ## The current floor
 
-`MIN_COVERAGE_PCT=0` in `.github/workflows/coverage.yml`. Slice 1
+`MIN_COVERAGE_PCT=49` in `.github/workflows/coverage.yml`. Slice 1
 of [#883](https://github.com/sebastienrousseau/dotfiles/issues/883)
 established the baseline at **~2.7% measured** (~613 of ~22 500 lines
 across 231 files). Successive slices raised it; the current measured
-value sits at **~47%**.
+value sits at **50.16%** (`6205/12371` lines, re-measured on the merged tree; gate floored at 49 for local<->CI drift + run variance) after the eighth core
+coverage-ratchet slice added `jwt` portability coverage and
+branch-driving function coverage for `apihealth`, `apiload`, and
+`apilatency`. This builds on the prior helper slice that drove
+`scripts/dot/commands/restore.sh` to 75.17%,
+`scripts/dot/commands/meta.sh` to 66.88%, `lib/dot/log.sh` to 59.56%,
+and `scripts/dot/commands/diagnostics.sh` to 49.63%, with additional
+git AI, hashsum, regex, jsonv, gl, and hex helper branch coverage.
+This builds on the prior core slice (`scripts/dot/commands/init.sh` at 72.09%,
+`scripts/dot/commands/manual.sh` at 62.50%,
+`scripts/dot/commands/core.sh` at 55.86%, and
+`scripts/dot/commands/secrets.sh` at 54.97%), the prior
+AI command slice (`defaults/dot_local/bin/executable_dot-ai-proxy` at
+76.00%, `scripts/dot/commands/agents.sh` at 66.15%, and
+`scripts/dot/commands/completion.sh` at 45.68%), the registry slice
+(`scripts/dot/commands/registry.sh` at 65.03%) and the macOS
+coverage-runner Perl timeout fallback, the aliases slice
+(`scripts/dot/commands/aliases.sh` at 70.00%), the tools/version-sync
+slice (`scripts/dot/commands/tools.sh` at 72.85%, `lib/dot/utils.sh` at
+73.24%, and `scripts/version-sync.sh` at 36.53%), the first core slice
+for `lib/dot/ui.sh`, and the #954 deep-branch pass for
+`scripts/theme/switch.sh`,
+`scripts/diagnostics/mcp-doctor.sh`, and Linux/WSL branches in
+`scripts/diagnostics/doctor.sh`.
 
 To tighten: