@sebastienrousseau/dotfiles 0.2.519 → 0.2.521

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

package/docs/operations/COVERAGE.md

@@ -1,204 +0,0 @@
----
-render_with_liquid: false
----
-
-# Code Coverage
-
-This page documents how coverage is measured, what the threshold is,
-how to run it locally, and how to triage a regression. Closes the
-docs slice of [#856](https://github.com/sebastienrousseau/dotfiles/issues/856).
-
-## Why pure bash xtrace (and not kcov)
-
-The repo's primary code surface is bash (~140 shell files under
-`scripts/`, hundreds more in `.chezmoitemplates/`). Standard
-language-specific coverage tools (`coverage.py`, `cargo tarpaulin`,
-`go cover`) don't apply.
-
-We originally targeted [kcov](https://github.com/SimonKagstrom/kcov),
-but kcov v43 on Ubuntu 24.04 + bash 5.2 cannot produce bash-script
-coverage in any configuration we tried:
-
-- Without bash debug symbols, kcov's ptrace backend fails to resolve
-  breakpoints and emits zero lines.
-- With `bash-dbgsym` installed, kcov switches into C-binary tracking
-  mode and emits coverage entries for bash's internal C headers
-  (`ctype.h`, `stdio.h`, `wchar.h`) instead of the `.sh` files we
-  want measured.
-
-Instead we use bash's own xtrace mechanism:
-
-```bash
-PS4='+@COV@:${LINENO}:${BASH_SOURCE}:@ '   # encode line + source
-BASH_ENV=/tmp/cov-setup.sh                  # `set -x` in every bash
-bash test.sh 2>traces/test.trace            # capture stderr per test
-```
-
-`BASH_ENV` is inherited by every non-interactive bash invocation, so
-subprocess `bash $SCRIPT_FILE` calls inside tests are also traced
-automatically. The runner parses every trace for `:LINENO:FILE:`
-matches and emits standard `lcov.info` that Codecov ingests natively.
-
-## Where it runs
-
-| Surface | What runs |
-|---|---|
-| **PR + push to main** | `.github/workflows/coverage.yml` → `Coverage / kcov` job → uploads lcov.info to Codecov and fails the build below `MIN_COVERAGE_PCT` (currently `58`, ratcheted up after measured integer-floor gains). |
-| **Local dev** | `bash tools/ci/run-coverage.sh` — works on Linux + macOS (xtrace is a bash primitive, no platform tools needed). |
-| **macOS dev** | Supported. xtrace-based instrumentation runs on macOS bash 3.2+ and Homebrew bash 5.x, with a Perl alarm fallback when GNU `timeout`/`gtimeout` is unavailable. |
-
-## The current floor
-
-`MIN_COVERAGE_PCT=58` in `.github/workflows/coverage.yml`. Slice 1
-of [#883](https://github.com/sebastienrousseau/dotfiles/issues/883)
-established the baseline at **~2.7% measured** (~613 of ~22 500 lines
-across 231 files). Successive slices raised it; the current measured
-value sits at **59.32%** (`7523/12682` lines, measured on v0.2.513; gate floored at 58 for local<->CI drift + run variance). This release now traces both mandatory unit and regression suites, replays the function exerciser's captured xtrace, and caches source-path normalization so aggregation completes in seconds instead of minutes. It builds on the earlier parser correction for nested Bash execution prefixes and deterministic branch-driving tests for Scorecard snapshots, examples coverage, and `httpdebug`. It builds on the eighth core
-coverage-ratchet slice, which added `jwt` portability coverage and
-branch-driving function coverage for `apihealth`, `apiload`, and
-`apilatency`. This builds on the prior helper slice that drove
-`scripts/dot/commands/restore.sh` to 75.17%,
-`scripts/dot/commands/meta.sh` to 66.88%, `lib/dot/log.sh` to 59.56%,
-and `scripts/dot/commands/diagnostics.sh` to 49.63%, with additional
-git AI, hashsum, regex, jsonv, gl, and hex helper branch coverage.
-This builds on the prior core slice (`scripts/dot/commands/init.sh` at 72.09%,
-`scripts/dot/commands/manual.sh` at 62.50%,
-`scripts/dot/commands/core.sh` at 55.86%, and
-`scripts/dot/commands/secrets.sh` at 54.97%), the prior
-AI command slice (`defaults/dot_local/bin/executable_dot-ai-proxy` at
-76.00%, `scripts/dot/commands/agents.sh` at 66.15%, and
-`scripts/dot/commands/completion.sh` at 45.68%), the registry slice
-(`scripts/dot/commands/registry.sh` at 65.03%) and the macOS
-coverage-runner Perl timeout fallback, the aliases slice
-(`scripts/dot/commands/aliases.sh` at 70.00%), the tools/version-sync
-slice (`scripts/dot/commands/tools.sh` at 72.85%, `lib/dot/utils.sh` at
-73.24%, and `scripts/version-sync.sh` at 36.53%), the first core slice
-for `lib/dot/ui.sh`, and the #954 deep-branch pass for
-`scripts/theme/switch.sh`,
-`scripts/diagnostics/mcp-doctor.sh`, and Linux/WSL branches in
-`scripts/diagnostics/doctor.sh`.
-
-To tighten:
-
-1. Land a slice that bumps measured coverage.
-2. Wait until two-three Codecov runs report a stable value (no
-   per-PR jitter).
-3. Edit `MIN_COVERAGE_PCT` upward, ideally by ≤15 percentage points
-   per bump.
-4. Note the floor change in the commit message + this page.
-
-### Why not the 95% target from #883
-
-The roadmap originally targeted ≥95% measured. The current xtrace-only
-measurement is **59.32%** on this codebase. The remaining gap is largely
-structural:
-
-- **System-mutation surface** — large parts of the repo orchestrate
-  real OS state (`chezmoi apply`, `gpg`, `pass`/`age` keystores,
-  `gsettings`, signal-driven app reload, `git reset --hard`,
-  filesystem backups). Exercising these requires either a destroyable
-  sandbox (Docker / VM) or per-call mocks for every system tool.
-- **Platform-gated branches** — every diagnostic and theme script
-  has Darwin / Linux / WSL forks. The xtrace runner only sees the
-  fork for the host it ran on; the others remain "uncovered"
-  forever from that one run's perspective. CI runs both macOS and
-  Linux but reports them separately.
-- **Interactive UIs** — `fzf`, `gum`, `cmatrix`, `niri`, and the
-  Ghostty/Tmux reload helpers can't return to the test under
-  `bash -x` within a timeout budget. These are excluded at the
-  aggregator level.
-- **Animated demo helpers** — same as interactive UIs.
-
-`tools/ci/run-coverage.sh` has a `SKIP_PATHS` set that removes
-genuinely-untestable scripts from the lcov denominator. Within the
-files that remain, individual mutation-only function bodies are
-fenced with `# LCOV_EXCL_START` / `# LCOV_EXCL_STOP` and a one-line
-rationale comment. Every exclusion line names the reason (`rm -rf
-real $HOME`, `signals live apps`, `gpg keystore`, etc.) so future
-maintainers can re-evaluate if the test infrastructure changes.
-
-The graduated approach in this doc replaces the original 95% target.
-The honest floor is the achievable one.
-
-## Running locally
-
-```bash
-bash tools/ci/run-coverage.sh   # Linux or macOS
-
-# Output:
-#   coverage/traces/<file>.trace  — per-test xtrace logs
-#   coverage/lcov.info            — lcov-format report Codecov ingests
-```
-
-Open `coverage/lcov.info` in any lcov visualizer
-(`genhtml coverage/lcov.info -o coverage/html`) for the per-file
-heatmap.
-
-## Triaging a regression
-
-When the `Coverage / kcov` PR check fails:
-
-1. Pull the workflow's `coverage-lcov` artifact (30-day retention).
-2. Compare against the previous main run by downloading its
-   `coverage-lcov` artifact too.
-3. Identify the file(s) where the line-coverage dropped.
-4. Either:
-   - Add tests covering the new code, or
-   - If the new code is provably unreachable in the test corpus
-     (e.g., a platform-specific branch only macOS tests exercise),
-     update the test suite to invoke it. Don't carve out global
-     exemptions — they accumulate.
-
-## Why not 100% yet
-
-The previous workflow advertised "100% Coverage" without measuring
-anything. Going from `0% measured` to `100% enforced` overnight is a
-recipe for either:
-
-- Suppressing the gate to ship anything ("just lower the threshold,
-  we'll fix it later"), or
-- Padding the test suite with assertions that don't actually
-  exercise the code under test.
-
-So this page documents a graduated approach: start with a measured
-floor at 50%, ratchet upward as the test surface catches up to the
-code surface. The previous aspirational "100%" labels in CI/job
-names + branch-protection contexts have been renamed to match
-reality (`Test / Unit Tests` instead of `Test / Unit Tests (100%
-Coverage)`).
-
-## Codecov integration
-
-Codecov (free OSS tier) is the canonical badge + PR-comment source.
-The upload uses the
-[`codecov/codecov-action`](https://github.com/codecov/codecov-action)
-in tokenless mode (works for public repos out of the box; private
-repos need `CODECOV_TOKEN`).
-
-The Codecov GitHub App posts a status check on each PR with the
-line-by-line diff coverage. Combine with this workflow's job-level
-threshold to get two independent signals.
-
-## Excluded paths
-
-`tools/ci/run-coverage.sh` excludes:
-
-- `tests/**` itself (don't measure coverage of the tests).
-- `.git/`, `node_modules/`.
-- Paths matched by `KCOV_EXCLUDE_PATTERN` (defaults reasonable).
-
-Included paths (`KCOV_INCLUDE_PATH`):
-
-- `scripts/`
-- `.chezmoitemplates/functions/`
-- `dot_local/bin/`
-
-Adjust via the env vars at the top of `run-coverage.sh`.
-
-## References
-
-- [Bash xtrace + PS4 + BASH_ENV docs](https://www.gnu.org/software/bash/manual/html_node/Bash-Variables.html).
-- [`tools/ci/run-coverage.sh`](https://github.com/sebastienrousseau/dotfiles/blob/main/tools/ci/run-coverage.sh).
-- [`.github/workflows/coverage.yml`](https://github.com/sebastienrousseau/dotfiles/blob/main/.github/workflows/coverage.yml).
-- Issue [#856](https://github.com/sebastienrousseau/dotfiles/issues/856) (closed) /
-  [#883](https://github.com/sebastienrousseau/dotfiles/issues/883) (coverage roadmap).

package/docs/operations/DRIFT.md

@@ -1,107 +0,0 @@
----
-render_with_liquid: false
----
-
-# Drift Detection & Remediation
-
-This page documents how this repo detects drift between the chezmoi
-source-of-truth and what's actually deployed on a host, how to read
-the report, and how to remediate. Managed under
-[#875](https://github.com/sebastienrousseau/dotfiles/issues/875).
-
-## What "drift" means here
-
-Four distinct classes are tracked. The same `dot drift` command (and
-the nightly CI workflow) surfaces all four.
-
-| Class | Meaning | How to detect | Typical fix |
-|---|---|---|---|
-| **Managed drift** | A chezmoi-managed file's deployed copy differs from what a fresh `chezmoi apply` would produce. The standard case. | `chezmoi status` (M / MM / A / R rows) | Either update the source so apply is idempotent, or accept the deployed change and re-add. |
-| **Untracked source** | The chezmoi source tree contains files git doesn't know about — usually in-progress local edits that haven't been committed. | `git -C <source-dir> ls-files --others --exclude-standard` | Commit, stash, or `.gitignore` the file. |
-| **Orphan deployed** | A file under `$HOME` was previously chezmoi-managed but the source has since been deleted. Chezmoi no longer claims it, so a fresh apply leaves it behind silently. | Inventoried in `${XDG_STATE_HOME}/dotfiles/orphans` (populated by `dot heal` / `dot drift`) | `chezmoi remove --force` the path, or re-add the source if the file is still wanted. |
-| **Stale source** | The deployed file is *newer* than its source. The next `chezmoi apply` would silently revert the user's hand-edit. Reverse-drift trap. | Compare mtimes for each managed target vs the resolved source-path | Promote the deployed change into the source (`chezmoi re-add`) or revert the deployed file. |
-
-## Reading the report
-
-```bash
-dot drift          # human-readable (uses the ui.sh formatting)
-dot drift --json   # single JSON object — used by the nightly workflow
-dot drift --diff   # also print `chezmoi diff` for managed drift
-```
-
-JSON shape:
-
-```json
-{
-  "managed_drift": 0,
-  "untracked_source": 0,
-  "orphan_deployed": 0,
-  "stale_source": 0,
-  "total": 0
-}
-```
-
-Exit code: `0` if every class is clean; `1` if any drift is found;
-`2` if a prerequisite (chezmoi, git) is missing.
-
-## How the nightly check works
-
-`.github/workflows/drift-detection.yml` runs `dot drift --json` against
-a fresh checkout of `main` every day at 04:00 UTC. If `total != 0`
-it opens (or updates) a tracking issue labelled
-`type:chore + priority:medium` with the JSON summary, full
-`chezmoi diff`, and `chezmoi status` attached as a workflow artifact.
-
-The workflow itself ignores the failing exit code (`|| true`) for the
-dashboard step — the actionable signal is the issue, not a red CI
-indicator.
-
-## Force a local drift check
-
-```bash
-dot drift            # default — what you'd run before opening a PR
-dot drift --json | jq '.'   # for scripting / dashboards
-```
-
-To force a full re-comparison after a tool upgrade or a force-apply:
-
-```bash
-chezmoi apply --refresh-externals   # refetch external sources
-dot drift                            # re-scan
-```
-
-## Historical incidents
-
-### 2026-05-12 — `core.hooksPath` drift
-
-The deployed `~/.gitconfig` contained a `hooksPath = ~/.git-templates/hooks`
-line that wasn't in `dot_gitconfig.tmpl`. The line had been added
-directly to the deployed file (manually, not via chezmoi), then sat
-silently for weeks while the global `commit-msg` hook (at
-`~/.config/git/hooks/commit-msg`) never fired — because `hooksPath`
-was pointing at an empty directory. The result: every commit
-authored on this machine silently shipped without the
-`Assisted-by:` trailer mandated by `dot_claude/CLAUDE.md`.
-
-Detection failure: no nightly drift check existed at the time.
-
-Resolution: commit `f060683b` brought `hooksPath` into the chezmoi
-template; this drift class is exactly what the new `stale_source`
-signal catches going forward.
-
-This incident is the canonical worked example for why the four-class
-report exists rather than just `chezmoi status`.
-
-## Configuration surface
-
-| Variable | Default | Purpose |
-|---|---|---|
-| `DOTFILES_DRIFT_SHOW_DIFF` | `0` | When `1`, append `chezmoi diff` (excluding scripts/install/tests) to the report. Equivalent to `--diff`. |
-
-## References
-
-- `scripts/diagnostics/drift-dashboard.sh` — the dashboard itself.
-- `.github/workflows/drift-detection.yml` — the nightly scanner.
-- `tests/unit/diagnostics/test_drift_dashboard.sh` — JSON contract test.
-- `dot heal` / `dot rollback` — drift remediation commands.
-- Issue [#875](https://github.com/sebastienrousseau/dotfiles/issues/875).