@sebastienrousseau/dotfiles 0.2.519 → 0.2.520

package/docs/migration/from-gnu-stow.md

@@ -0,0 +1,165 @@
+---
+render_with_liquid: false
+---
+
+<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->
+<!-- Copyright (c) 2015-2026 Sebastien Rousseau -->
+
+# Migrating from GNU Stow
+
+Stow builds a symlink farm: `~/.bashrc` is a symlink into
+`~/dotfiles/bash/.bashrc`. This framework renders real files into
+`$HOME` from a source tree. That difference is the whole migration —
+everything else follows from it.
+
+Be honest about whether you want this. If your setup is "symlink a
+dozen files on one machine", Stow is doing that job well and the
+migration will not repay itself. The reason to move is templating,
+multiple machines, or the tooling around the files.
+
+## Concept mapping
+
+| Stow | Here |
+|---|---|
+| `~/dotfiles/<package>/` | `defaults/` (one tree, not per-package) |
+| `stow bash` | `dot sync` (applies everything) |
+| `stow -D bash` | `chezmoi forget <file>`, then `dot sync` |
+| `stow -n` (simulate) | `dot diff` or `dot sync --check` |
+| `.stow-local-ignore` | `.chezmoiignore` |
+| Symlinks in `$HOME` | Real files in `$HOME` |
+| Per-host: separate packages or branches | `.tmpl` files with `{{ if }}` |
+
+## 1. Record what Stow currently owns
+
+Symlinks are self-describing, which makes this the easiest inventory
+of any migration:
+
+```sh
+find "$HOME" -maxdepth 3 -type l -lname "*dotfiles*" \
+  -printf '%p -> %l\n' 2>/dev/null | tee ~/stow-inventory.txt
+```
+
+On macOS (BSD `find` has no `-printf`):
+
+```sh
+find "$HOME" -maxdepth 3 -type l | while read -r l; do
+  case "$(readlink "$l")" in *dotfiles*) echo "$l -> $(readlink "$l")";; esac
+done | tee ~/stow-inventory.txt
+```
+
+Back up the real content, following the links:
+
+```sh
+tar -czhf ~/stow-backup-$(date +%F).tar.gz -C "$HOME" \
+  $(sed 's| ->.*||; s|^'"$HOME"'/||' ~/stow-inventory.txt)
+```
+
+`-h` is the important flag: it dereferences symlinks and archives the
+actual files.
+
+## 2. Unstow before installing
+
+This is the step people skip, and it is the one that matters. If you
+install over a live symlink farm, `chezmoi apply` will try to replace
+symlinks with regular files and the result is confusing.
+
+```sh
+cd ~/dotfiles
+stow -D */          # remove every package's links
+find "$HOME" -maxdepth 3 -type l -lname "*dotfiles*" 2>/dev/null   # expect empty
+```
+
+Your `~/dotfiles` directory still holds the real files. Nothing is lost.
+
+## 3. Install
+
+```sh
+bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh)"
+```
+
+## 4. Import your files
+
+Stow packages flatten into a single tree. Copy each package's contents
+into `$HOME` and add them:
+
+```sh
+cd ~/dotfiles
+for pkg in */; do
+  pkg="${pkg%/}"
+  echo "== $pkg"
+  ( cd "$pkg" && find . -type f -print0 ) | while IFS= read -r -d '' rel; do
+    rel="${rel#./}"
+    mkdir -p "$(dirname "$HOME/$rel")"
+    cp "$pkg/$rel" "$HOME/$rel"
+    dot add "$HOME/$rel"
+  done
+done
+```
+
+Review before committing anything — this is a good moment to drop the
+files you have not opened in three years:
+
+```sh
+dot status
+cd "$(dot cd)" && git status
+```
+
+## 5. Replace per-host packages with templates
+
+If you had `bash-work/` and `bash-home/` packages, collapse them:
+
+```text
+{{ if eq .chezmoi.hostname "work-laptop" }}
+export HTTP_PROXY=http://proxy.corp:3128
+{{ end }}
+```
+
+Available variables: `.chezmoi.os`, `.chezmoi.arch`, `.chezmoi.hostname`,
+`.chezmoi.username`, `.chezmoi.osRelease.id`, plus this project's
+`.profile` and `.features.*` from `defaults/.chezmoidata.toml`.
+
+Test a template without applying:
+
+```sh
+chezmoi execute-template < defaults/dot_bashrc.tmpl
+```
+
+## 6. Apply and verify
+
+```sh
+dot diff
+dot sync
+dot doctor
+
+# Nothing should be a symlink into ~/dotfiles any more:
+find "$HOME" -maxdepth 3 -type l -lname "*dotfiles*" 2>/dev/null
+```
+
+## 7. Retire the old tree
+
+After a few days:
+
+```sh
+mv ~/dotfiles ~/dotfiles.stow.bak     # rename, do not delete
+# delete ~/dotfiles.stow.bak once you are sure
+```
+
+## Rolling back
+
+```sh
+bash ~/.dotfiles/scripts/uninstall.sh --force
+mv ~/dotfiles.stow.bak ~/dotfiles     # if you renamed it
+cd ~/dotfiles && stow */
+```
+
+## What you gain, what you lose
+
+**Gain:** templating (the thing Stow structurally cannot do); one tree
+instead of a package-per-tool layout; the `dot` CLI; multi-shell
+parity; secrets management; signed releases.
+
+**Lose:** the elegance of the symlink model — editing `~/.bashrc` no
+longer edits your repo directly, so you edit the source and run
+`dot sync` (or `dot add` after the fact). Stow is ~5k lines of Perl
+with essentially no runtime dependencies; this pulls in chezmoi. And
+Stow's mental model fits in a paragraph, which has real value.

package/docs/migration/from-plain-chezmoi.md

@@ -0,0 +1,148 @@
+---
+render_with_liquid: false
+---
+
+<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->
+<!-- Copyright (c) 2015-2026 Sebastien Rousseau -->
+
+# Migrating from plain chezmoi
+
+The shortest migration here, because there is no engine change: this
+framework *is* chezmoi, plus a source-tree layout, a CLI, and the
+tooling around them. Your templates, your `.chezmoidata`, and your
+muscle memory all carry over.
+
+You can also stop after step 2 and keep using `chezmoi` commands
+directly forever. Nothing here replaces chezmoi; `dot` shells out to it.
+
+## What actually changes
+
+| Plain chezmoi | Here |
+|---|---|
+| Source at `~/.local/share/chezmoi` | Source at `~/.dotfiles`, with `.chezmoiroot` pointing chezmoi at `defaults/` |
+| Everything at the source root | `defaults/` = your files; `bin/`, `lib/`, `scripts/`, `docs/`, `tests/` = the framework |
+| `chezmoi apply` | `dot sync` (which runs `chezmoi apply` with sensible exclusions) |
+| `chezmoi diff` / `status` | `dot diff` / `dot status` — same thing, prettier |
+| — | `dot doctor`, `dot health`, `dot heal`, `dot rollback`, `dot attest` |
+| `chezmoi secret` | `dot secrets` (age + sops) |
+| `run_onchange_` scripts | same, plus `install/provision/` |
+
+**`.chezmoiroot` is the key idea.** It contains `defaults`, so chezmoi
+treats `~/.dotfiles/defaults/` as the source root. Framework code sits
+outside that directory and is therefore never deployed to `$HOME`.
+
+## 1. Back up and record
+
+```sh
+chezmoi source-path
+chezmoi managed > ~/chezmoi-managed.txt
+wc -l ~/chezmoi-managed.txt
+
+cp -a "$(chezmoi source-path)" ~/chezmoi-source-backup-$(date +%F)
+tar -czf ~/chezmoi-backup-$(date +%F).tar.gz -C "$HOME" -T ~/chezmoi-managed.txt
+```
+
+Commit and push your existing source repo if it has a remote. That is
+the real backup.
+
+## 2. Two paths
+
+**A. Keep your own repo** (you have a dotfiles repo you want to keep
+as the source of truth): install the framework, then move your files
+into `defaults/`.
+
+**B. Adopt this repo's defaults** and layer your changes on top:
+
+```sh
+bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh)"
+```
+
+Path A continues below.
+
+## 3. Install and relocate your source tree
+
+```sh
+old_source="$(chezmoi source-path)"
+
+bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh)"
+
+# Copy your source files under defaults/, preserving chezmoi's naming.
+rsync -av --exclude '.git' "$old_source/" ~/.dotfiles/defaults/
+```
+
+Then reconcile the chezmoi-metadata files, which now exist in both
+places — merge yours into the framework's rather than overwriting:
+
+| File | What to do |
+|---|---|
+| `.chezmoidata.toml` | **Merge.** The framework's carries `dotfiles_version`, `profile`, and `features`; keep those and add your keys. |
+| `.chezmoiignore` | Merge; the framework's entries are feature-flag-gated. |
+| `.chezmoi.toml.tmpl` | Merge your prompts into the framework's. |
+| `.chezmoitemplates/` | Merge; name collisions are the only risk. |
+| `.chezmoiscripts/`, `run_*` | Copy across as-is. |
+
+Sanity-check the merge before applying anything:
+
+```sh
+cd ~/.dotfiles
+chezmoi --source "$PWD" data | head -40
+chezmoi --source "$PWD" managed | head
+```
+
+## 4. Preview, then apply
+
+```sh
+dot diff              # or: chezmoi diff — identical underneath
+dot sync --check      # dry run
+dot sync
+dot doctor
+```
+
+Confirm nothing was dropped:
+
+```sh
+while read -r f; do
+  [ -e "$f" ] || echo "MISSING: $f"
+done < ~/chezmoi-managed.txt
+```
+
+## 5. Optional: adopt the extras
+
+None of these are required; adopt them when you want them.
+
+```sh
+dot secrets-init      # age-based secrets
+dot theme list        # wallpaper-driven theming
+dot profile show      # profiles and feature flags
+dot completion fish > ~/.config/fish/completions/dot.fish
+```
+
+## Rolling back
+
+The gentlest rollback of any of these guides, because chezmoi is still
+the engine:
+
+```sh
+chezmoi --source ~/chezmoi-source-backup-<date> apply
+bash ~/.dotfiles/scripts/uninstall.sh --force
+```
+
+Or simply point chezmoi back at your old source and carry on:
+
+```sh
+chezmoi init --source ~/chezmoi-source-backup-<date>
+```
+
+## What you gain, what you lose
+
+**Gain:** the `dot` CLI (diagnostics, repair, rollback, attestation,
+fleet); a curated multi-shell configuration with parity across bash,
+zsh, fish, nushell and PowerShell; secrets, theming and provisioning
+already wired; a test suite and CI you can run against your own
+changes; signed, attested releases.
+
+**Lose:** simplicity. Plain chezmoi is one binary and your files;
+this adds a source-tree convention, a CLI layer, and opinions about
+shell configuration you may not share. If you already have a chezmoi
+setup you are happy with, "it works and I understand every line" is a
+perfectly good reason to stay.

package/docs/migration/from-yadm.md

@@ -0,0 +1,187 @@
+---
+render_with_liquid: false
+---
+
+<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->
+<!-- Copyright (c) 2015-2026 Sebastien Rousseau -->
+
+# Migrating from yadm
+
+yadm is the closest neighbour: both track real files in `$HOME` with
+git, both template per host, both encrypt secrets. The migration is
+mostly a mechanical re-home of files plus a translation of yadm's
+alternate-file suffixes into chezmoi templates.
+
+## Concept mapping
+
+| yadm | Here | Note |
+|---|---|---|
+| `yadm add` / `yadm commit` | `dot add` then a normal `git commit` in the source dir | Source tree is a plain git repo |
+| `$HOME` **is** the work tree | Files live in `defaults/` and are *rendered* into `$HOME` | The big conceptual change |
+| `##os.Linux`, `##hostname.foo` suffixes | `{{ if eq .chezmoi.os "linux" }}` in a `.tmpl` | One file with branches, not N files |
+| `yadm alt` | `chezmoi apply` | Automatic; no separate step |
+| `yadm encrypt` (GPG) | `dot secrets` (age + sops) | Different crypto; see below |
+| `yadm bootstrap` | `install/provision/run_onchange_*` | Runs on apply, idempotent |
+| `yadm status` / `diff` | `dot status` / `dot diff` | Same intent |
+
+## 1. Inventory and back up
+
+```sh
+yadm list -a > ~/yadm-inventory.txt
+wc -l ~/yadm-inventory.txt
+tar -czf ~/yadm-backup-$(date +%F).tar.gz -C "$HOME" -T ~/yadm-inventory.txt
+```
+
+Keep `yadm-inventory.txt`: it is your checklist, and step 5 diffs
+against it.
+
+## 2. Install alongside yadm
+
+The installer does not touch yadm's repo (`~/.local/share/yadm/repo.git`)
+or its config, so both can coexist while you migrate.
+
+```sh
+bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh)"
+dot version
+```
+
+If you want to bring your *own* dotfiles repo rather than the
+maintainer's defaults, use `dot init` instead:
+
+```sh
+dot init yourusername --dry-run    # prints the resolved URL and target dir
+dot init yourusername
+```
+
+## 3. Move files across
+
+Plain (non-alternate) files first:
+
+```sh
+while read -r f; do
+  case "$f" in
+    *##*) continue ;;            # alternates handled in step 4
+  esac
+  dot add "$f"
+done < ~/yadm-inventory.txt
+```
+
+`dot add` wraps `chezmoi add`, so a file in `~/.config/foo/bar` lands
+at `defaults/dot_config/foo/bar`, and `~/.gitconfig` at
+`defaults/dot_gitconfig`.
+
+## 4. Translate alternates into templates
+
+For each `##`-suffixed file, replace the family with one `.tmpl`.
+
+yadm:
+
+```text
+~/.gitconfig##os.Darwin
+~/.gitconfig##os.Linux
+```
+
+Here — `defaults/dot_gitconfig.tmpl`:
+
+```text
+[user]
+    name = {{ .name }}
+    email = {{ .email }}
+{{ if eq .chezmoi.os "darwin" }}
+[credential]
+    helper = osxkeychain
+{{ else if eq .chezmoi.os "linux" }}
+[credential]
+    helper = cache --timeout=3600
+{{ end }}
+```
+
+The common yadm conditions map as:
+
+| yadm suffix | chezmoi expression |
+|---|---|
+| `##os.Darwin` | `eq .chezmoi.os "darwin"` |
+| `##os.Linux` | `eq .chezmoi.os "linux"` |
+| `##hostname.foo` | `eq .chezmoi.hostname "foo"` |
+| `##user.alice` | `eq .chezmoi.username "alice"` |
+| `##distro.Ubuntu` | `eq .chezmoi.osRelease.id "ubuntu"` |
+| `##default` | the `{{ else }}` branch |
+
+Verify before applying — templates fail loudly, but only when rendered:
+
+```sh
+chezmoi execute-template < defaults/dot_gitconfig.tmpl
+dot diff
+```
+
+## 5. Migrate encrypted files
+
+yadm uses GPG; this framework uses age via sops. There is no automatic
+converter, and that is deliberate — re-encrypting secrets is a step
+you should perform consciously.
+
+```sh
+# Decrypt with yadm, in a directory that is not the repo.
+mkdir -p /tmp/secrets-migration && cd /tmp/secrets-migration
+yadm decrypt
+
+# Set up age and re-encrypt.
+dot secrets-init                    # generates the age key
+dot secrets-create                  # creates the encrypted store
+dot secrets set GITHUB_TOKEN        # one per secret, prompts for the value
+dot secrets list
+
+cd - && rm -rf /tmp/secrets-migration
+```
+
+Details and the provider model: [`../security/SECRETS.md`](../security/SECRETS.md).
+
+## 6. Apply and verify
+
+```sh
+dot diff          # review every pending change
+dot sync          # apply
+dot doctor        # health check
+```
+
+Then diff against the inventory to catch anything missed:
+
+```sh
+while read -r f; do
+  [ -e "$HOME/$f" ] || echo "MISSING: $f"
+done < ~/yadm-inventory.txt
+```
+
+## 7. Retire yadm
+
+Only after a full working day on the new setup:
+
+```sh
+yadm list -a > ~/yadm-final-check.txt   # last snapshot, keep it
+rm -rf ~/.local/share/yadm
+rm -rf ~/.config/yadm
+# and remove the yadm package via your package manager
+```
+
+## Rolling back
+
+At any point before step 7, yadm is untouched:
+
+```sh
+bash ~/.dotfiles/scripts/uninstall.sh --force
+tar -xzf ~/yadm-backup-<date>.tar.gz -C "$HOME"
+yadm status
+```
+
+## What you gain, what you lose
+
+**Gain:** one templated file instead of alternate families; the `dot`
+CLI (`doctor`, `health`, `heal`, `rollback`, `attest`); multi-shell
+parity including fish, nushell and PowerShell; signed and attested
+releases; fleet commands for more than one machine.
+
+**Lose:** `$HOME` is no longer a git work tree, so `git status` in your
+home directory stops being meaningful — you use `dot status` instead.
+GPG-encrypted files become age/sops. yadm is a single ~2k-line script;
+this is a larger surface. And yadm's bootstrap is one file, whereas
+provisioning here is spread across `install/provision/`.

package/docs/operations/PERFORMANCE_BUDGETS.md

@@ -0,0 +1,196 @@
+---
+render_with_liquid: false
+---
+
+# Performance Budgets
+
+Every operation this repo owns falls into one of four performance tiers. Each tier has a **hard budget** enforced by `benches/test_perf_budgets.sh`. If a change pushes an operation past its budget's headroom, CI fails.
+
+## The tiers
+
+| Tier | Budget | What belongs here |
+|---|---|---|
+| **INSTANT** | ≤ **500ms** | Anything a human sees at a shell prompt |
+| **FAST** | ≤ **2000ms** | Heavier gates + sandboxed CLI reads |
+| **MEDIUM** | ≤ **5000ms** | Full diagnostic runs |
+| **ACCEPTED-SLOW** | documented | Multi-second ops that are legitimately slow (see below) |
+| **OUT-OF-SCOPE** | not gated | Multi-minute ops we don't gate per-run |
+
+## Reference baselines (2026-08-30, `rousseau-cachyos-geekom-a9`, Ryzen AI 9 HX 370)
+
+All medians in milliseconds. Budget = 2× median (or the tier ceiling, whichever is larger).
+
+### INSTANT tier
+
+| Operation | Baseline | Budget | Headroom |
+|---|---:|---:|---:|
+| `dot version` | 10 | 500 | 50× |
+| `dot help` | 13 | 500 | 38× |
+| `dot help <cmd>` | 15 | 500 | 33× |
+| `dot search <keyword>` | 15 | 500 | 33× |
+| iCloud script single-run | 15 | 500 | 33× |
+
+
+### FAST tier
+
+Currently empty.
+
+`dot status` and `dot diff` were placed here at 2000ms against reference
+medians of 1510 ms and 1420 ms — 1.3× and 1.4× headroom, short of the ≥ 2×
+this document requires of every budget. They have since moved to MEDIUM; see
+that section for the measurements that prompted it.
+
+> The baselines of 28 ms and 32 ms recorded before those were not real. The
+> perf sandbox never created chezmoi's source directory, so both commands
+> aborted immediately with *"no such file or directory"* — and `_measure`
+> discarded exit codes, so the gate timed the failure path and called it
+> excellent. The sandbox now links the repo into `XDG_DATA_HOME`.
+
+The QA gates and test suites that used to sit in this tier moved to GATES
+below: they are not interactive operations, so a ceiling defined by
+human-perceived latency never described them.
+
+### MEDIUM tier
+
+| Operation | Baseline | Budget | Headroom |
+|---|---:|---:|---:|
+| `dot status` (sandbox) | 2329 | 5000 | 2.1× |
+| `dot diff` (sandbox) | 2157 | 5000 | 2.3× |
+| `dot doctor` | 3892 | 5000 | 1.3× |
+| `bench.sh --quick` | 826 | 5000 | 6× |
+
+The `dot status` and `dot diff` baselines are the **worst** of the two hosted
+runners, not the reference machine: macOS measured 2290 ms / 2157 ms and Ubuntu
+2329 ms / 2136 ms, against 1139 ms / 1174 ms locally. Two unrelated platforms
+agreeing within 8% is a property of the commands rather than of one slow
+runner — both shell out to chezmoi, which walks the whole source tree, and that
+is disk-bound. A budget taken from the faster machine would have been a gate
+that only ever fired on other people's hardware.
+
+`dot doctor` and `bench.sh --quick` are diagnostics that report findings through
+their exit status — `dot doctor` exits 1 whenever it finds issues, and `bench.sh` exits 1
+when a shell breaches its own startup threshold. They are gated with
+`_gate_diag`, which permits exit 1 but still fails on 2+ (not-found,
+permission, signal, syntax error). That is far narrower than the blanket
+`|| true` it replaced.
+
+### GATES tier (CI quality gates and test suites)
+
+Budgets are 2× the median measured on the **slowest supported platform**,
+not the fastest. Medians below: `rousseau-mbp-m1`, macOS 26 (Darwin 25.6),
+2026-08-30.
+
+| Operation | macOS median | Linux median | Budget | Headroom |
+|---|---:|---:|---:|---:|
+| `check-version-consistency.sh` | 68 | 14 | 500 | 7.4× |
+| `docs-coverage.sh` | 969 | 148 | 2000 | 2.1× |
+| iCloud regression test (12 assertions) | 494 | 94 | 1000 | 2.0× |
+| iCloud unit test (29 assertions) | 1743 | 498 | 3500 | 2.0× |
+| iCloud manifest test (11 assertions) | 1575 | — † | 5000 | 3.2× |
+| `traceability-coverage.sh` | 2389 | 623 | 5000 | 2.1× |
+| `test_dot_subcommand_smoke.sh` | 3785 | 1308 | 7500 | 2.0× |
+| `test_dot_help_registry_symmetry.sh` | 4449 | 1381 | 9000 | 2.0× |
+
+† The manifest test hashes an entire sandbox tree before and after every
+scenario, so it is disk-bound in a way the other gates are not. Its budget is
+set at 3.2× the macOS median rather than the 2.0× used above, deliberately:
+`dot status` and `dot diff` were first budgeted at 1.3× and 1.4×, and both
+breached on the first CI run that measured them. The Linux median is left
+unfilled until CI reports one — guessing it would defeat the point of a table
+of measurements.
+
+These gates run **3–6× slower on macOS than on Linux** — fork/exec is markedly
+more expensive there and every one of them is fork-heavy shell. CI covers both
+platforms, so the original Linux-only calibration could not hold, and five of
+these sat red as a result. Re-capture the Linux column when convenient; it is
+carried over from the 2026-08-30 Ryzen baseline and is not the binding
+constraint.
+
+### ACCEPTED-SLOW (documented, not gated per-run)
+
+| Operation | Baseline | Reason |
+|---|---:|---|
+| `test_dot_help_flag_universal.sh` | ~11s | Invokes `dot help --help` on ~100 commands via subshell each. The coverage it provides justifies the cost; regression is caught by `benches/test_help_gates_wall_clock.sh` at the suite level. |
+
+### OUT-OF-SCOPE (not gated per-run)
+
+| Operation | Why we don't gate |
+|---|---|
+| `chezmoi apply` | Fresh macOS: minutes. Depends on iCloud sync + package installs. Gated at suite level only. |
+| `install.sh` full | Downloads + installs packages. Network-bound. |
+| `dot upgrade` | Runs `mise upgrade`, `chezmoi apply`, package manager upgrades. |
+| Full test suite | 15+ minutes on CI. Gated by workflow timeout, not per-run assertion. |
+
+## Ratchet vs aspiration
+
+The budgets above are **regression gates**, not aspirations. If a real optimisation lowers a baseline, edit the doc + the perf test to lower the budget too. If a change pushes something over the budget, the test fails and CI blocks the merge.
+
+The aspirational shell-startup target (`<30ms`) is tracked separately in `benches/bench.sh` — that's a bench, not a budget.
+
+## Adding a new operation
+
+When you add a new script that runs at a shell prompt:
+
+1. Time it 5 runs on a warm system: `for _ in {1..5}; do time bash your-script; done`
+2. Take the median.
+3. Place it in the tier where `budget ≥ 2 × median`. If a median is 400ms it goes in FAST (500ms is uncomfortably tight); if it's 300ms, INSTANT is fine.
+4. Add it to `benches/test_perf_budgets.sh` in the correct tier section.
+5. Add its baseline to this doc.
+
+## Where the enforcement lives
+
+- **Per-op budget test**: `benches/test_perf_budgets.sh`
+- **Suite-level wall-clock ratchet**: `benches/test_help_gates_wall_clock.sh`
+- **CI wiring**: `.github/workflows/ci.yml`, job `quality-performance` — runs on
+  ubuntu-latest and macos-latest for every PR, with no `|| true` and no budget
+  scaling. On the gates the hosted macOS runner is comparable to or faster than
+  the reference machine — docs-coverage 679 ms vs 969, traceability 1775 vs
+  2389, help-registry 3318 vs 4449, `dot doctor` 1746 vs 4423. The exception is
+  anything that drives chezmoi over the whole source tree: `dot status` and
+  `dot diff` measured ~2× the local median on **both** hosted platforms, which
+  is why they sit in MEDIUM rather than FAST. Budget a new operation against the
+  slowest platform it will run on, not against this machine.
+
+### How the time is measured
+
+`_measure` uses the `time` keyword with `TIMEFORMAT='%3R'`, not `date +%s%N`.
+
+`%N` is a GNU extension. BSD `date` — macOS 14 and earlier — copies the literal
+`N` through, so every arithmetic conversion failed, `_measure` returned nothing,
+and an empty median compares as `0` against any budget. The gate reported every
+budget met on those machines, for any command, including one that could not
+parse. `time` is a shell builtin, is millisecond-accurate in bash 3.2, and needs
+no external clock at all.
+
+Two consequences worth keeping:
+
+- `_gate_max_rc` rejects a non-numeric median outright rather than comparing it.
+  Both fields go through `-gt` / `-le`, where bash reads a non-numeric operand
+  as `0` — so a gate that cannot measure would otherwise report success.
+- `tests/regression/test_gate_integrity.sh` puts a `date` without `%N` first on
+  `PATH` and requires the same verdicts. A future timing rewrite that
+  reintroduces the dependency fails there rather than going quiet.
+
+## Environment knobs
+
+| Variable | Default | Effect |
+|---|---|---|
+| `PERF_BUDGET_PERCENT` | `100` | Scales every budget. `0` makes them all impossible — that is how `test_gate_integrity.sh` proves the gate actually fires. |
+| `PERF_GATE_FILTER` | *(unset)* | Runs only gates whose label contains this substring. Skipped gates never call `test_start`, so `TESTS_RUN == PASSED + FAILED` still holds. |
+| `DOT_CLI` | `bin/dot` | Points the `dot` gates at another binary, so breakage detection can be exercised against a deliberately corrupted CLI. |
+
+## When a budget fires
+
+The error looks like:
+
+```
+✗ instant_dot_help: median=612ms EXCEEDS budget=500ms
+```
+
+Steps:
+
+1. Bisect the change that pushed it over.
+2. Fix the regression, or
+3. If the increase is legitimate (real new work), move the operation to the next tier + update this doc + `test_perf_budgets.sh` in the same PR.
+
+**Never silently bump the budget.** The tier a thing lives in is a promise to users.