@sebastienrousseau/dotfiles 0.2.520 → 0.2.521

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

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

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

@@ -1,36 +0,0 @@
----
-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/guides/INSTALL.md

@@ -1,144 +0,0 @@
----
-render_with_liquid: false
----
-
-# Install
-
-Set up on macOS, Linux, or WSL in 3 to 5 minutes.
-
-**You will need:** `git` and `curl`.
-
-**Default shell:** Fish. You can change it after you install.
-
-## Install
-
-```bash
-bash -c "$(
-  curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh
-)"
-```
-
-Then restart your terminal or run `exec $SHELL`.
-
-## Verify
-
-```bash
-dot --version        # Confirm installation
-dot doctor           # Check shell, git, and tools
-dot help             # Browse available commands
-```
-
-## Choose a shell
-
-Fish is the default shell. To switch to Zsh or Nushell, edit `~/.dotfiles/.chezmoidata.toml`:
-
-```toml
-default_shell = "zsh"
-```
-
-Supported values: `zsh`, `fish`, `nushell`.
-
-Then apply the change:
-
-```bash
-dot apply
-```
-
-## Feature flags
-
-Turn optional tools on or off after setup. Edit `.chezmoidata.toml`:
-
-```toml
-[features]
-zsh = true         # Zsh shell configuration
-fish = true        # Fish shell configuration
-nushell = true     # Nushell configuration
-nvim = true        # Neovim IDE configuration
-tmux = true        # Terminal multiplexer
-nix = true         # Nix package manager integration
-```
-
-## Update
-
-```bash
-dot update
-```
-
-## Next steps
-
-1. Run `dot learn` to take a guided tour.
-2. Add your own tweaks in `~/.config/shell/custom/`.
-3. Read the [Utilities and `dot` CLI](../reference/UTILS.md) reference.
-
----
-
-## Advanced
-
-### Local source install
-
-Clone the repo first, then run the installer from your local copy:
-
-```bash
-git clone https://github.com/sebastienrousseau/dotfiles.git ~/.dotfiles
-cd ~/.dotfiles
-./install.sh
-```
-
-### Minimal install
-
-Install only shells and core tools. This skips editor and terminal extras:
-
-```bash
-./install.sh --minimal
-```
-
-### Non-interactive install
-
-Use this mode for CI or scripts that run without user input:
-
-```bash
-DOTFILES_SILENT=1 DOTFILES_NONINTERACTIVE=1 \
-  bash -c "$(
-    curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh
-  )"
-```
-
-### Nix
-
-```bash
-nix develop ~/.dotfiles/nix
-nix profile install ~/.dotfiles/nix#dot-utils
-```
-
-### Offline bundle
-
-On a machine with internet access, create a bundle:
-
-```bash
-dot bundle ~/Downloads
-```
-
-Copy the archive to the target machine. Then unpack and install:
-
-```bash
-tar --zstd -xf dotfiles_offline_bundle_*.tar.zst -P
-cd ~/.dotfiles
-./install.sh --force
-```
-
-### Uninstall
-
-```bash
-chezmoi purge
-rm -rf ~/.dotfiles
-rm -rf ~/.local/share/chezmoi ~/.local/share/dotfiles.log
-```
-
-### Signed contributions
-
-All commits must be signed. See [Contributing](https://github.com/sebastienrousseau/dotfiles/blob/main/CONTRIBUTING.md) for details.
-
----
-
-- [Troubleshooting](TROUBLESHOOTING.md)
-- [Support matrix](../reference/SUPPORT_MATRIX.md)

package/docs/guides/MACOS_ICLOUD_SYMLINKS.md

@@ -1,121 +0,0 @@
----
-render_with_liquid: false
----
-
-# macOS iCloud Drive Symlinks
-
-On macOS, this dotfiles setup can (safely) symlink personal directories into iCloud Drive so `~/Desktop`, `~/Documents`, `~/Downloads`, `~/Movies`, `~/Music`, `~/Pictures`, and `~/Public` all live in iCloud and back up automatically.
-
-The mechanism is `defaults/run_before_macos-icloud-symlinks.sh.tmpl`, which chezmoi runs before **every** `apply` — not once, and not only when the script changes. That is deliberate: a run-once script gets a single attempt, and on a fresh Mac that attempt lands while iCloud Drive is still syncing the folder tree down, so every candidate would skip and the one chance would be spent. Running each time lets it link whatever has become safe to link since the last apply. Repeat runs are no-ops that cost a few milliseconds.
-
-## `~/Desktop` and `~/Documents` are a special case
-
-macOS has its own **"Desktop & Documents Folders"** iCloud feature (System Settings -> Apple Account -> iCloud -> iCloud Drive -> Options). When it is on, macOS itself syncs those two folders, and it marks them in the iCloud container by putting symlinks there pointing *back* at your home directory:
-
-```text
-com~apple~CloudDocs/Desktop    -> ~/Desktop
-com~apple~CloudDocs/Documents  -> ~/Documents
-```
-
-Check whether it is on:
-
-```bash
-defaults read com.apple.finder FXICloudDriveDesktop    # 1 = Desktop sync on
-defaults read com.apple.finder FXICloudDriveDocuments  # 1 = Documents sync on
-```
-
-**If those return `1`, `~/Desktop` and `~/Documents` are already fully synced to iCloud and across your devices — by macOS, not by this script.** They will show as `SKIP ... iCloud source is itself a symlink` in the log. That is the correct outcome, not a failure.
-
-Do **not** apply the manual migration recipe below to `~/Desktop` or `~/Documents` while native sync is on: you would be moving data into a symlink that points back at its own source, fighting a feature macOS is already managing. Turn native sync off first if you genuinely want the symlink approach — but for these two folders the native feature is the better mechanism, since Finder, Migration Assistant, and iOS all understand it.
-
-The symlink approach in this guide is for the folders macOS does *not* cover natively: `~/Downloads`, `~/Movies`, `~/Music`, `~/Pictures`, `~/Public`.
-
-## Safety guarantees
-
-This script is the **replacement** for a previous `symlink_*.tmpl` set that had a data-loss bug (see #1018): chezmoi's built-in symlink handling does `rm -rf $target; ln -s $source $target`, which destroys real content if the target directory has data.
-
-The current script's contract is:
-
-| Situation | What the script does |
-|---|---|
-| `~/$name` is already the correct symlink to iCloud | no-op |
-| `~/$name` is a symlink pointing somewhere else | **skip, log** — never overwrite your own link |
-| `~/$name` is a directory with any content (including `.DS_Store`) | **skip, log** — never delete your data |
-| `~/$name` is an empty directory | `rmdir` (fails safely if non-empty due to a race) + create symlink |
-| `~/$name` is a regular file | **skip, log** — never touch |
-| `~/$name` does not exist | create symlink directly |
-| iCloud source `com~apple~CloudDocs/$name` does not exist | **skip, log** — iCloud may still be syncing |
-| iCloud Drive is not set up on the Mac | **skip everything, log** — no partial state |
-| iCloud source `com~apple~CloudDocs/$name` is itself a symlink | **skip, log** — macOS's native Desktop & Documents sync owns it (see below) |
-
-The script has **two kill-switches**:
-
-- `touch ~/.dotfiles.icloud-skip` — permanent per-machine opt-out
-- `DOTFILES_ICLOUD_SYMLINKS=0` — env var, one run only
-
-And a **dry-run mode**:
-
-- `DOTFILES_ICLOUD_DRY_RUN=1` — log every decision, take no action
-
-## Rescue: how to link a directory that has content
-
-If one of the non-native folders (`~/Downloads`, `~/Movies`, `~/Music`, `~/Pictures`, `~/Public`) already has content and you want it in iCloud — the example uses `Documents`, which applies only if you have turned native Desktop & Documents sync **off**:
-
-```bash
-# 1. Move your data into iCloud MANUALLY
-mv ~/Documents/* ~/Documents/.* "~/Library/Mobile Documents/com~apple~CloudDocs/Documents/" 2>/dev/null
-
-# 2. Verify iCloud has everything
-ls -la "~/Library/Mobile Documents/com~apple~CloudDocs/Documents/"
-
-# 3. Now the dir is empty — chezmoi's next apply will do the rmdir + symlink
-rmdir ~/Documents          # sanity check: this succeeds only if truly empty
-chezmoi apply
-```
-
-## After the links exist: what changes
-
-Linking a folder into iCloud does exactly what it says, and that has consequences worth understanding *before* you migrate rather than after.
-
-**Storage.** Everything saved to a linked folder counts against your iCloud quota, not just local disk. `~/Downloads` is the one that catches people out.
-
-**Deletion.** Deleting a file from a linked folder deletes it from iCloud, and therefore from every device signed into that account. There is no local-only copy any more. This is inherent to symlinking and is not something the hook can guard.
-
-**Eviction.** macOS may evict a synced file's contents to reclaim disk space, leaving a placeholder behind. Reading it downloads it again — so a script that walks one of these folders can block on the network where it used to return instantly.
-
-**Two things in this repository write into these folders.** Neither runs during `chezmoi apply`; both are commands you invoke deliberately:
-
-| What | Where | Why it matters after linking |
-|---|---|---|
-| `scripts/theme/merge-wallpaper.sh` | `~/Pictures/Wallpapers` (override with `DOTFILES_WALLPAPER_DIR`) | Merges a light/dark pair into one `.heic` and then **deletes both source files**. After linking, that pair is consumed from iCloud. Point `DOTFILES_WALLPAPER_DIR` at a local directory to keep the library off iCloud. |
-| `defaults/dot_config/mpv/mpv.conf` | `~/Pictures/Screenshots` | `screenshot-directory` is set here, so mpv screenshots land in iCloud. |
-
-Nothing else in this repository writes into the seven folders, and chezmoi itself never touches them: they are listed in the Darwin block of `.chezmoiignore.tmpl`, and `chezmoi managed` reports none of them among the paths it controls.
-
-## Log
-
-Every run appends to `$XDG_STATE_HOME/dotfiles/icloud-symlinks.log` (default: `~/.local/state/dotfiles/icloud-symlinks.log`). Grep for `SKIP` to see why a candidate wasn't linked, or `LINK` to see what was created.
-
-## Belt-and-braces protection
-
-The same directory names are listed in `defaults/.chezmoiignore.tmpl`'s Darwin block, so even if the script never ran, chezmoi's regular `apply` would still refuse to touch these paths on macOS. Two independent layers of protection.
-
-## Tests
-
-Three suites, 52 assertions, all of them run under `/bin/bash` 3.2 as well as bash 5:
-
-- `tests/unit/misc/test_macos_icloud_symlinks.sh` — 29 assertions covering every branch of the refusal matrix.
-- `tests/regression/test_macos_icloud_symlinks_safety.sh` — 12 assertions on the data-loss invariants, checking that named canary files survive.
-- `tests/regression/test_macos_icloud_symlinks_manifest.sh` — 11 assertions that hash the *whole* sandbox tree before and after, so a file lost in a path nobody named still shows up. Verified to drop from 11/11 to 4/11 against a deliberately reintroduced #1018.
-
-`tests/regression/test_gate_integrity.sh` adds 10 more asserting those gates fail when they should. If any of them regress, CI blocks the merge.
-
-## Manual override: disable entirely
-
-If you never want the automation:
-
-```bash
-touch ~/.dotfiles.icloud-skip
-```
-
-The script sees this file in the first 5 lines of execution and exits 0 immediately, without touching the filesystem.

package/docs/guides/NEOVIM_IDE_GUIDE.md

@@ -1,61 +0,0 @@
----
-render_with_liquid: false
----
-
-# Neovim
-
-## Modern Core
-
-- **Requirement**: Neovim >= 0.11.2. The config checks this at startup.
-- **Configuration**: Modular, lazy-loaded configuration based on `lazy.nvim`.
-- **Completion**: `blink.cmp` for fast, keystroke-level completion with LSP, snippets, and path sources.
-- **UI**: Snacks.nvim dashboard, notifications, status line, buffer line, and file explorer.
-- **LSP**: Full LSP support for diagnostics, code actions, and more, managed by `mason.nvim`.
-
-## Language Support
-
-- **Rust**: Out-of-the-box support with `rustaceanvim`.
-- **Python**: Full support with `basedpyright`, `ruff`, and `venv-selector`.
-- **Web**: Support for web development with `prettier` and `eslint`.
-
-## AI Integration
-
-- **Copilot**: `copilot.lua` for code completion. Run `:Copilot auth` to sign in.
-- **Copilot Chat**: AI sidebar for asking questions and getting help (`<leader>cc`).
-
-## VS Code Parity
-
-- **Problem Panel**: `trouble.nvim` for a VS Code-like problems panel (`<leader>xx`).
-- **Search & Replace**: `nvim-spectre` for project-wide search and replace (`<leader>S`).
-- **Auto-Pairs**: Automatically closes brackets and pairs (via `blink.cmp` auto-brackets).
-- **TODOs**: Highlights `TODO` and `FIXME` comments.
-- **Session**: Auto-restores your last session.
-- **Snippets**: Native `vim.snippet` engine (Neovim 0.11+).
-
-## Keybindings
-
-| Key | Action |
-| --- | --- |
-| `<Space>ff` | Find Files |
-| `<Space>fg` | Grep (Search) text |
-| `<Space>fb` | File browser |
-| `<Space>fp` | Projects |
-| `<Space>e` | Toggle File Explorer |
-| `<Space>a` | Add file to Harpoon |
-| `<Ctrl>e` | Open Harpoon menu |
-| `gd` | Go to Definition |
-| `gr` | Go to References |
-| `<leader>ca` | Code actions |
-| `<leader>cf` | Format code |
-| `<leader>cr` | Rename symbol |
-| `<leader>tt` | Toggle terminal |
-| `<leader>tn` | Test nearest |
-| `<leader>tf` | Test file |
-| `<leader>ts` | Test suite |
-| `<F5>` | Continue (Debug) |
-| `<F10>` | Step over (Debug) |
-| `<F11>` | Step into (Debug) |
-| `<F12>` | Step out (Debug) |
-| `<leader>cc` | Toggle Copilot Chat |
-| `<leader>xx` | Toggle Diagnostics (Trouble) |
-| `<leader>S` | Toggle Spectre (Search/Replace) |