@sebastienrousseau/dotfiles 0.2.500 → 0.2.502

package/docs/manual/04-cookbook/03-faq.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Cookbook: Frequently Asked Questions
 
 ## General
@@ -36,6 +40,7 @@ CIELAB distances approximate human perception. A Δ in RGB might look identical
 ### Why not pre-built themes like Catppuccin or Rosé Pine?
 
 Two reasons:
+
 1. **Maintenance** — 100+ themes × 20+ applications = thousands of template variables to keep in sync. Generation from wallpapers eliminates that.
 2. **User agency** — users bring their own wallpapers. The theme adapts to them, not the other way around.
 
@@ -52,6 +57,7 @@ You don't directly — the accent hue is extracted from the wallpaper. But `_com
 ### Can I use my own theme without a wallpaper?
 
 Not directly — the engine expects a source image. You could:
+
 1. Pick a wallpaper whose palette you want
 2. Let the engine generate the theme
 3. Lock the generated `.toml` entry by copying to a non-regenerated path
@@ -116,6 +122,7 @@ DOTFILES_DEBUG=1 zsh -i -c exit 2>&1 | grep -E '\[debug [0-9]+ms\]'
 ```
 
 Common culprits:
+
 - nvm loading Node on every shell (use lazy loading)
 - `mise activate` with aggressive hook-env (set `activate_aggressive = false`)
 - Plugin manager scanning for updates
@@ -153,6 +160,7 @@ To maximize adoption and contribution. MIT is compatible with commercial use; co
 ### Why no GUI configurator?
 
 Text + Git is the optimal interface for a workstation baseline:
+
 - Versioned (Git history)
 - Reproducible (same input → same output)
 - Auditable (diff-able)

package/docs/manual/05-appendices/A-platform-matrix.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Appendix A: Platform Support Matrix
 
 ## Supported Platforms

package/docs/manual/05-appendices/B-security-checklist.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Appendix B: Security Checklist
 
 Run this checklist after a fresh install and quarterly afterwards.
@@ -40,10 +44,12 @@ Run this checklist after a fresh install and quarterly afterwards.
 If a secret leak is detected:
 
 1. **Contain** — remove from history, force-push
+
    ```sh
    git filter-repo --path <file> --invert-paths
    git push --force
    ```
+
 2. **Rotate** — change the leaked secret upstream (Stripe key, SSH key, etc.)
 3. **Audit** — check who/what had access
 4. **Notify** — inform affected parties if required

package/docs/manual/05-appendices/C-glossary.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Appendix C: Glossary
 
 | Term | Definition |

package/docs/manual/05-appendices/D-bibliography.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Appendix D: Bibliography
 
 Cited works and recommended reading.
@@ -51,4 +55,4 @@ Cited works and recommended reading.
 
 ## Author
 
-- **Rousseau, S.** *Dotfiles v0.2.500.* <https://github.com/sebastienrousseau/dotfiles>
+- **Rousseau, S.** *Dotfiles v0.2.501.* <https://github.com/sebastienrousseau/dotfiles>

package/docs/manual/05-appendices/E-license.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Appendix E: License
 
 ## MIT License

package/docs/manual/_toc.yml

@@ -2,7 +2,7 @@
 # Determines concatenation order for single-page HTML/PDF/EPUB
 title: "The .dotfiles Manual"
 subtitle: "A Trusted Agent Workstation for macOS, Linux, and WSL"
-version: "0.2.500"
+version: "0.2.502"
 
 sections:
   - file: 00-introduction.md

package/docs/manual/command-index.md

@@ -1,32 +1,40 @@
+---
+render_with_liquid: false
+---
+
 # Command Index
 
 Alphabetical list of `dot` subcommands referenced in the manual.
 
 - `dot agent`
+- `dot agents check`
+- `dot agents list`
+- `dot agents render`
+- `dot agents`
 - `dot ai`
 - `dot apply --dry-run`
 - `dot apply`
 - `dot attest`
-- `dot benchmark --detailed`
-- `dot benchmark`
 - `dot bundle`
 - `dot cache-refresh`
 - `dot cd`
 - `dot chaos`
-- `dot clean-cache`
 - `dot commit`
 - `dot diff`
 - `dot doctor --json`
 - `dot doctor`
-- `dot drift`
 - `dot edit`
 - `dot env`
+- `dot fleet apply --dry-run`
+- `dot fleet apply`
 - `dot fleet attest`
 - `dot fleet diff`
 - `dot fleet sync`
 - `dot fleet`
 - `dot heal`
 - `dot help`
+- `dot init --dry-run`
+- `dot init`
 - `dot learn`
 - `dot lint`
 - `dot load-bench`
@@ -38,8 +46,11 @@ Alphabetical list of `dot` subcommands referenced in the manual.
 - `dot mode`
 - `dot packages`
 - `dot perf`
-- `dot prewarm`
 - `dot profile`
+- `dot registry info`
+- `dot registry list`
+- `dot registry search`
+- `dot registry`
 - `dot rollback`
 - `dot score`
 - `dot secrets rotate`
@@ -51,8 +62,5 @@ Alphabetical list of `dot` subcommands referenced in the manual.
 - `dot theme toggle`
 - `dot theme`
 - `dot tune`
-- `dot update`
 - `dot upgrade`
-- `dot verify --security`
-- `dot verify`
 - `dot version`

package/docs/manual/concept-index.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Concept Index
 
 Alphabetical list of concepts covered in the manual.

package/docs/manual/index.md

@@ -0,0 +1,66 @@
+---
+title: "The .dotfiles Manual"
+description: "A trusted agent workstation baseline for macOS, Linux, and WSL."
+render_with_liquid: false
+---
+
+# The .dotfiles Manual
+
+A trusted agent workstation baseline for macOS, Linux, and WSL. Chezmoi handles templating and platform differences; the `dot` CLI coordinates lifecycle operations on top.
+
+This manual is generated from the Markdown sources in [`docs/manual/`](https://github.com/sebastienrousseau/dotfiles/tree/master/docs/manual) and published in nine formats per release. The HTML edition you are reading is the canonical online version.
+
+## Read it your way
+
+- **Web (multi-page)** — browse the chapters below
+- **Single-page HTML, PDF, EPUB, ASCII text** — attached to every [GitHub Release](https://github.com/sebastienrousseau/dotfiles/releases/latest)
+- **CLI** — `dot manual` opens the manual locally; `dot manual pdf` downloads the PDF; `dot manual text` pipes the ASCII edition to your pager
+
+## Contents
+
+### [Introduction](00-introduction.md)
+
+The audience, scope, conventions, and where the manual is published.
+
+### Concepts
+
+- [Architecture](01-concepts/01-architecture.md) — repository layout, chezmoi templating, the `dot` dispatcher
+- [Trust model](01-concepts/02-trust-model.md) — signing, attestation, SBOM, policy gates
+- [Theme engine](01-concepts/03-theme-engine.md) — wallpaper-driven theming across apps
+- [Fleet](01-concepts/04-fleet.md) — multi-workstation coordination and drift detection
+- [Self-healing](01-concepts/05-self-healing.md) — automatic remediation and rollback
+
+### Tutorials
+
+- [First install](02-tutorials/01-first-install.md)
+- [Add a wallpaper-driven theme](02-tutorials/02-add-wallpaper.md)
+- [Create an agent profile](02-tutorials/03-create-profile.md)
+- [Encrypt a secret](02-tutorials/04-encrypt-secret.md)
+- [Deploy to a fleet](02-tutorials/05-deploy-fleet.md)
+
+### Reference
+
+- [`dot` CLI](03-reference/01-dot-cli.md) — every subcommand
+- [Config files](03-reference/02-config-files.md) — every `~/.config/dotfiles/*` path
+- [Environment](03-reference/03-environment.md) — every variable read by the framework
+- [Templates](03-reference/04-templates.md) — every `{{ .var }}` reference
+- [Feature flags](03-reference/05-feature-flags.md)
+
+### Cookbook
+
+- [Recipes](04-cookbook/01-recipes.md)
+- [Troubleshooting](04-cookbook/02-troubleshooting.md)
+- [FAQ](04-cookbook/03-faq.md)
+
+### Appendices
+
+- [A — Platform matrix](05-appendices/A-platform-matrix.md)
+- [B — Security checklist](05-appendices/B-security-checklist.md)
+- [C — Glossary](05-appendices/C-glossary.md)
+- [D — Bibliography](05-appendices/D-bibliography.md)
+- [E — License](05-appendices/E-license.md)
+
+### Indexes
+
+- [Concept index](concept-index.md)
+- [Command index](command-index.md)

package/docs/operations/ATTESTATION.md

@@ -1,8 +1,13 @@
+---
+render_with_liquid: false
+---
+
 # Workstation Attestation
 
 `dot attest` exports a machine-readable record of the current workstation state.
 
 It captures:
+
 - dotfiles version
 - platform and architecture
 - Git signing settings

package/docs/operations/CI_CADENCE.md

@@ -0,0 +1,107 @@
+---
+render_with_liquid: false
+---
+
+# CI Cadence
+
+This page tabulates every GitHub Actions workflow in `.github/workflows/`
+with its trigger cadence and the rationale for that cadence. Maintained
+under [issue #861](https://github.com/sebastienrousseau/dotfiles/issues/861).
+
+## Cadence rules
+
+We use four cadence buckets:
+
+| Bucket | When | Used for |
+|---|---|---|
+| **Event** | `push`, `pull_request`, `merge_group` | Code-change gates — must run on every PR. |
+| **Weekly** | `schedule:` Monday or Sunday | Drift detection, beta-tool watch, extended platform matrices. |
+| **Monthly** | (none currently) | Long-running audits, historical scans. |
+| **Manual** | `workflow_dispatch` only | Releases, ad-hoc tooling. |
+
+**Anti-rule:** no workflow runs on `cron: '* * * *'` (daily) unless its
+output is consumed daily by something downstream. Nothing today meets
+that bar; see "Why no daily jobs" below.
+
+## Workflow cadence table
+
+| Workflow | Triggers | Schedule (UTC) | Why this cadence |
+|---|---|---|---|
+| `ci.yml` | event + schedule | Mon 06:00 (weekly) | Lint / test on every PR; weekly schedule catches drift from external dependencies (apt mirrors, Homebrew bottles) even when no code lands. |
+| `ci-enforced.yml` | event | — | Strict gates fire on every PR; no scheduled run (covered by ci.yml weekly). |
+| `codeql.yml` | event + schedule | Mon 06:00 (weekly) | Source-code SAST. Weekly schedule catches new CodeQL rule packs. |
+| `compliance-guard.yml` | event | — | Policy enforcement on every PR; no need to schedule. |
+| `cross-platform-test.yml` | event + schedule | Sun 07:00 (weekly) | Validates BSD vs GNU tool divergence on every PR; weekly catches GitHub-hosted-runner image updates. |
+| `devcontainer-prebuild.yml` | event + schedule | Mon 03:00 (weekly) | Pre-build the devcontainer image weekly so first `Open in Codespaces` is fast. |
+| `manual-publish.yml` | manual only | — | Release-trigger flow; never scheduled. |
+| `nightly.yml` | schedule + manual | **Sun 02:00 (weekly)** | Was daily; flipped to weekly under [#861](https://github.com/sebastienrousseau/dotfiles/issues/861). Jobs (beta-tool detection, extended OS matrix on macos-15-intel/macos-14, dependency-report) don't need daily cadence. |
+| `npm-publish.yml` | release tag | — | Trigger: `push` of a version tag. |
+| `policy-bundle-release.yml` | manual + release | — | Manual / release-trigger only. |
+| `pr-signature.yml` | pull_request | — | Verifies PR description has the branding signature. |
+| `reliability-gate.yml` | event | — | Reliability audit on every PR; no scheduled cadence. |
+| `reusable-*.yml` (×7) | callable | — | Called by other workflows; not directly triggered. |
+| `sbom-diff.yml` | pull_request | — | Generates SBOM diff per PR. |
+| `security-enhanced.yml` | event + schedule | **Sun 02:00 (weekly)** | Was daily; reduced to weekly in earlier hardening. Per-PR runs cover the active-change case. |
+| `security-release.yml` | release tag | — | SLSA provenance on release; never scheduled. |
+| `sync-versions.yml` | manual | — | Version-bump tooling. |
+| `update-deps.yml` | schedule | Mon 08:00 (weekly) | Dependabot is the primary path; this is a belt-and-suspenders weekly sweep. |
+
+## Why no daily jobs
+
+We reviewed every workflow with maintainer Sebastien Rousseau on
+2026-05-12 and concluded:
+
+1. **No external signal needs daily polling.** Dependency updates flow
+   through Dependabot (push-driven, not poll-driven). Beta-tool
+   detection in `nightly.yml` checks for major Chezmoi / ShellCheck
+   updates — these ship every few months, not days. CVE scans run on
+   every PR (`sbom-diff.yml`) plus a weekly aggregate
+   (`security-enhanced.yml`).
+
+2. **No downstream consumer reads daily artifacts.** No external
+   dashboard, no published feed, no alert ingester depends on a daily
+   nightly artifact. The artifacts are inspected ad-hoc.
+
+3. **Daily cadence was vestigial.** `nightly.yml` had cron `0 2 * * *`
+   from an earlier era when the workflow ran the full test matrix; the
+   matrix has since moved into `ci-enforced.yml` (event-driven), but
+   the cron was never updated. Confirmed via `git log` of the file.
+
+If any of these conditions changes (e.g., we add a publishing pipeline
+that needs daily artifacts), the appropriate path is a new `daily-checks.yml`
+workflow with explicit cadence rationale documented here — *not* flipping
+an existing weekly back to daily.
+
+## Cost impact of the daily → weekly flip
+
+Before (daily nightly):
+
+- 7 runs/week × ~40 min total CI minutes per run = **~280 min/week**
+- ~14,560 minutes/year (~243 hours of CI compute)
+
+After (weekly nightly):
+
+- 1 run/week × ~40 min = **~40 min/week**
+- ~2,080 minutes/year (~35 hours)
+
+**Net saving: ~208 hours of CI compute per year (~85% reduction)** on
+the nightly workflow alone. GitHub-hosted minutes are billed per
+runner-minute; saving aligns with the project's "zero-debt, no waste"
+mandate.
+
+## Reviewing this page
+
+When adding a new workflow:
+
+1. Pick a bucket from the rules at the top of this page.
+2. Add the row to the table — include the **why**, not just the cron
+   expression. Future maintainers should be able to decide whether a
+   cadence is still load-bearing.
+3. If proposing a daily cadence, justify why a weekly version doesn't
+   meet the need in the workflow's PR description.
+
+## References
+
+- [`nightly.yml`](../../.github/workflows/nightly.yml) — the workflow whose cadence flip triggered this page.
+- [`security-enhanced.yml`](../../.github/workflows/security-enhanced.yml) — earlier daily→weekly reduction.
+- Issue [#861](https://github.com/sebastienrousseau/dotfiles/issues/861).

package/docs/operations/CI_COMPOSITES.md

@@ -0,0 +1,156 @@
+---
+render_with_liquid: false
+---
+
+# CI Composite Actions
+
+This page documents the repo-local composite actions under
+`.github/actions/`. These exist so the most-repeated CI setup blocks
+have one canonical implementation, one cache key shape, and one place
+to bump pins. Managed under
+[#879](https://github.com/sebastienrousseau/dotfiles/issues/879).
+
+## Available actions
+
+### `setup-chezmoi`
+
+Path: `.github/actions/setup-chezmoi/action.yml`
+
+Installs the pinned `chezmoi` binary (using the SHA256-verified
+installer at `scripts/ci/install-chezmoi-verified.sh` when the repo is
+checked out, falling back to `get.chezmoi.io` otherwise), caches the
+result, and appends the bin-dir to `$GITHUB_PATH`.
+
+```yaml
+- name: Setup Chezmoi
+  uses: ./.github/actions/setup-chezmoi
+  # `version` defaults to env.CHEZMOI_VERSION. Override explicitly when
+  # the calling workflow has no env block (e.g. drift-detection):
+  with:
+    version: '2.70.3'
+```
+
+Inputs:
+
+| Name | Default | Purpose |
+|---|---|---|
+| `version` | `env.CHEZMOI_VERSION` | Pinned release tag (no leading `v`). |
+| `cache` | `true` | When `false`, skip `actions/cache`. |
+| `cache-key-prefix` | `chezmoi` | Override if a workflow wants a private cache scope. |
+| `bin-dir` | `~/.local/bin` | Install location. |
+
+Outputs:
+
+| Name | Purpose |
+|---|---|
+| `version` | The version that ended up installed. |
+| `path` | Absolute path to the chezmoi binary. |
+
+Cache key shape: `<prefix>-<runner.os>-<runner.arch>-<version>`.
+`runner.arch` is included explicitly so the Apple-Silicon (arm64) and
+Intel (x64) macOS runners don't share a cache entry — that previously
+caused subtle binary-mismatch failures.
+
+### `setup-mise`
+
+Path: `.github/actions/setup-mise/action.yml`
+
+Installs `mise` (jdx/mise) and optionally runs `mise install` against
+`mise.toml` to materialise the managed toolchain. Caches both the
+mise binary and `~/.local/share/mise` (the tool install root, keyed
+by lockfile hash).
+
+```yaml
+- name: Setup mise
+  uses: ./.github/actions/setup-mise
+  with:
+    install-tools: 'true'
+```
+
+Inputs:
+
+| Name | Default | Purpose |
+|---|---|---|
+| `version` | `latest` | mise version to install. Specify a pinned version to enable bin caching. |
+| `cache` | `true` | Cache the mise binary + tool root. |
+| `cache-key-prefix` | `mise` | Override the cache scope. |
+| `install-tools` | `false` | When `true`, run `mise install` after setup. |
+| `bin-dir` | `~/.local/bin` | Install location for the mise binary. |
+
+Outputs: `version` (installed mise version) and `path` (absolute path
+to the mise binary).
+
+## Why composite actions (vs reusable workflows)
+
+The repo already uses reusable workflows for big-grain CI steps
+(`reusable-shell-lint.yml`, `reusable-test-suite.yml`, etc.). Composite
+actions cover a different need:
+
+- **Reusable workflows** wrap a whole job — same triggers, same runner,
+  same job name. Useful for "lint shell" or "run the test suite".
+- **Composite actions** wrap a step sequence. Cheap to drop into any
+  job without restructuring the job graph.
+
+Setup steps (install + cache + path) are the textbook composite-action
+case: they're short, every caller wants the same behaviour, and
+inlining them everywhere creates exactly the duplication this issue
+called out.
+
+## Current adopters
+
+`setup-chezmoi` is wired into:
+
+| Workflow | Job(s) |
+|---|---|
+| `ci-enforced.yml` | `test-matrix` |
+| `ci.yml` | `test-linux`, `test-macos`, `quality-idempotency`, `performance` |
+| `nightly.yml` | `extended-os-matrix`, `nightly-perf-bench` |
+| `drift-detection.yml` | `drift-scan` |
+
+Total: 8 call sites converted. The net workflow LOC delta is
+~−34 lines (52 deletions, 18 additions); ongoing additions to either
+workflow set will widen the gap.
+
+`setup-mise` ships ready for use but has zero current callers because
+no workflow currently installs mise (the maintainer relies on it
+locally only). When a future workflow needs `cargo`, `bun`, `go`, or
+`rust` toolchains via the canonical version manager, this composite
+is the canonical entry point.
+
+## Pinning policy
+
+Both composite actions internally pin every external action they use
+to a 40-char commit SHA (e.g.
+`actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5`).
+Dependabot picks these up via the standard `github-actions` ecosystem
+configuration in `.github/dependabot.yml`.
+
+## Bumping a pin
+
+To upgrade `chezmoi` for every CI job at once:
+
+```bash
+# Find the new release:
+gh api repos/twpayne/chezmoi/releases/latest --jq '.tag_name'
+
+# Update the three workflow-level env declarations:
+for f in .github/workflows/{ci.yml,ci-enforced.yml,nightly.yml}; do
+  sed -i.bak 's/CHEZMOI_VERSION: "[^"]*"/CHEZMOI_VERSION: "X.Y.Z"/' "$f"
+  rm "$f.bak"
+done
+
+# Drift-detection has its own pin (no env block):
+sed -i.bak "s/version: '[^']*'/version: 'X.Y.Z'/" .github/workflows/drift-detection.yml
+rm .github/workflows/drift-detection.yml.bak
+```
+
+Or rely on `update-deps.yml`, which already automates the env-block
+bump on a weekly schedule.
+
+## References
+
+- `.github/actions/setup-chezmoi/action.yml`
+- `.github/actions/setup-mise/action.yml`
+- `scripts/ci/install-chezmoi-verified.sh` — the SHA-pinned installer
+  the chezmoi composite prefers when available.
+- Issue [#879](https://github.com/sebastienrousseau/dotfiles/issues/879).

package/docs/operations/COMPLETIONS.md

@@ -0,0 +1,123 @@
+---
+render_with_liquid: false
+---
+
+# Zsh Completion Cache Lifecycle
+
+This page documents how zsh completion compilation works in this repo
+and how to force a rebuild. Managed under
+[#864](https://github.com/sebastienrousseau/dotfiles/issues/864).
+
+## The Pieces
+
+Three caches cooperate to keep `compinit` fast without compromising
+correctness:
+
+1. **The compinit dump** —
+   `$XDG_CACHE_HOME/zsh/zcompdump-$ZSH_VERSION`. Built by
+   `compinit -d <path>` from the fpath corpus. Encodes which file
+   provides each completion function. Per-zsh-version so an OS upgrade
+   doesn't silently serve a stale binary index.
+
+2. **The compinit dump bytecode** — `<dump>.zwc`. Built by
+   `zcompile` in the background after the dump is rebuilt. Zsh prefers
+   the `.zwc` form on subsequent shells, skipping re-parse.
+
+3. **fpath bytecode siblings** — `_<tool>.zwc` next to each
+   `_<tool>` source file under `~/.local/share/zsh/completions/`.
+   Built once per chezmoi apply by
+   `run_onchange_after_zcompile-completions.sh.tmpl` (so this happens
+   *outside* the critical shell-start path). Zsh prefers the `.zwc`
+   when autoloading the corresponding completion function.
+
+## Flow on Shell Start
+
+```
+zsh starts
+  → sources rc.d (no compinit yet)
+  → registers a `preexec` (or `precmd`) hook
+  → returns to prompt
+user presses Tab (or `precmd` fires)
+  → `compinit -d $XDG_CACHE_HOME/zsh/zcompdump-$ZSH_VERSION`
+    or `compinit -C -d <dump>` if the dump is < 24 hours old
+  → background `zcompile` of the dump
+  → first tab-completion uses the precompiled `.zwc` for each tool
+```
+
+## Flow on Chezmoi Apply
+
+```
+chezmoi apply
+  → if completion sources changed, run_onchange fires
+    run_onchange_after_zcompile-completions.sh.tmpl
+  → walks ~/.local/share/zsh/completions/
+  → for each _<tool> file whose .zwc is missing or stale:
+      zsh -c "zcompile <file>"
+  → reports compiled=N skipped=M
+```
+
+## Configuration Surface
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `DOTFILES_ENABLE_COMPINIT` | 1 on `laptop`/`desktop` profiles, 0 elsewhere | Whether to load the completion subsystem at all. Non-laptop profiles skip the runtime cost but still benefit from precompiled `.zwc` files if present. |
+| `DOTFILES_DEFER_COMPINIT` | 1 | When 1, compinit runs on first `preexec`. When 0, runs on `precmd`. |
+| `DOTFILES_FAST` | 0 | When 1, the entire completion path is skipped. |
+| `DOTFILES_ULTRA_FAST` | 0 | Same as `DOTFILES_FAST` but more aggressive. |
+| `DOTFILES_SKIP_ZCOMPILE` | 0 | When 1, the run_onchange hook does not precompile fpath files. Used in CI / minimal images where bytecode isn't needed. |
+| `XDG_CACHE_HOME` | `$HOME/.cache` | Standard XDG override; the dump path is `$XDG_CACHE_HOME/zsh/zcompdump-$ZSH_VERSION`. |
+
+## Force Rebuild
+
+When completions go stale (e.g., after a tool upgrade):
+
+```bash
+# Invalidate the compinit dump — next shell rebuilds it.
+rm -f "${XDG_CACHE_HOME:-$HOME/.cache}/zsh/zcompdump-${ZSH_VERSION}"
+rm -f "${XDG_CACHE_HOME:-$HOME/.cache}/zsh/zcompdump-${ZSH_VERSION}.zwc"
+
+# Force regeneration of fpath bytecode siblings:
+find ~/.local/share/zsh/completions -name '*.zwc' -delete
+chezmoi apply ~  # re-runs the run_onchange hook
+```
+
+Or, equivalently, `dot heal` (which calls both in sequence).
+
+## Measured Cost
+
+The current dotfiles ship with `compinit` deferred to first-prompt,
+which means shell *startup* time is already nearly minimal — zsh
+doesn't parse the fpath corpus until tab-completion is invoked. The
+precompiled `.zwc` files cut down the *first tab-completion* latency
+per tool, not shell-start latency. On a 2026 M-series macOS host the
+P50 for `time zsh -i -c exit` measured at 39 ms before this change
+and 39 ms after — the change pays off when the user starts typing,
+not before.
+
+This makes the lifecycle policy still worth shipping:
+
+- Cleaner cache layout (XDG-cache, version-keyed).
+- Bytecode siblings auto-picked on non-laptop profiles (which skip
+  compinit entirely) so completion is still fast even without the
+  full subsystem.
+- A documented force-rebuild path.
+
+## Skip Rules
+
+The run_onchange hook skips itself when:
+
+- `DOTFILES_SKIP_ZCOMPILE=1` (CI / minimal images).
+- `zsh` is not on PATH (servers without an interactive shell).
+- `~/.local/share/zsh/completions/` doesn't exist.
+
+System fpath directories (Homebrew, `/usr/local/share/zsh`) are
+intentionally NOT precompiled — the package manager already manages
+their lifecycle.
+
+## References
+
+- [`dot_config/zsh/rc.d/30-options.zsh.tmpl`](../../dot_config/zsh/rc.d/30-options.zsh.tmpl) — the deferred-compinit logic.
+- [`run_onchange_after_zcompile-completions.sh.tmpl`](../../run_onchange_after_zcompile-completions.sh.tmpl) — the apply-time precompile hook.
+- [`zsh` completion docs](https://zsh.sourceforge.io/Doc/Release/Completion-System.html).
+- ADR-002 (Shell Performance Optimization).
+- Issue [#864](https://github.com/sebastienrousseau/dotfiles/issues/864).