@sebastienrousseau/dotfiles 0.2.520 → 0.2.521

package/docs/migration/from-yadm.md

@@ -1,187 +0,0 @@
----
-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/ARCHITECTURE_ROADMAP.md

@@ -1,7 +0,0 @@
-# Architecture Roadmap
-
-Historical architecture planning has been consolidated into the canonical
-[`../../ROADMAP.md`](../../ROADMAP.md).
-
-Current architecture decisions belong in `docs/architecture/`; future roadmap
-items belong in the root roadmap or in GitHub issues and milestones.

package/docs/operations/ATTESTATION.md

@@ -1,44 +0,0 @@
----
-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
-- active agent profile
-- MCP strict-mode audit status
-- tracked agent card, profile, and registry data
-- policy bundles
-- model and prompt registries
-
-Run:
-
-```bash
-dot attest
-dot attest --json
-dot attest -j
-dot attest --write ~/.local/state/dotfiles/attestations/workstation.json
-dot attest -w ~/.local/state/dotfiles/attestations/workstation.json
-dot attest --fleet-store /srv/dotfiles-fleet
-dot attest -F /srv/dotfiles-fleet -I engineering
-```
-
-The default output path is `~/.local/state/dotfiles/attestations/workstation-attestation.json`.
-
-Fleet export writes:
-
-- `<fleet-store>/<fleet-id>/<hostname>/workstation-attestation.json`
-- timestamped copies for retention
-
-Governance evidence is embedded directly in the JSON output. That includes:
-
-- policy bundle definitions
-- model registry metadata
-- prompt registry metadata
-- tracked MCP policy and registry artifacts

package/docs/operations/CI_CADENCE.md

@@ -1,107 +0,0 @@
----
-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`](https://github.com/sebastienrousseau/dotfiles/blob/main/.github/workflows/nightly.yml) — the workflow whose cadence flip triggered this page.
-- [`security-enhanced.yml`](https://github.com/sebastienrousseau/dotfiles/blob/main/.github/workflows/security-enhanced.yml) — earlier daily→weekly reduction.
-- Issue [#861](https://github.com/sebastienrousseau/dotfiles/issues/861).

package/docs/operations/CI_COMPOSITES.md

@@ -1,156 +0,0 @@
----
-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 `tools/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`
-- `tools/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

@@ -1,123 +0,0 @@
----
-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`](https://github.com/sebastienrousseau/dotfiles/blob/main/defaults/dot_config/zsh/rc.d/30-options.zsh.tmpl) — the deferred-compinit logic.
-- [`run_onchange_after_zcompile-completions.sh.tmpl`](https://github.com/sebastienrousseau/dotfiles/blob/main/defaults/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).