@sebastienrousseau/dotfiles 0.2.501 → 0.2.503

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/CI_COMPOSITES.md

@@ -17,7 +17,7 @@ to bump pins. Managed under
 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
+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`.
 
@@ -151,6 +151,6 @@ bump on a weekly schedule.
 
 - `.github/actions/setup-chezmoi/action.yml`
 - `.github/actions/setup-mise/action.yml`
-- `scripts/ci/install-chezmoi-verified.sh` — the SHA-pinned installer
+- `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

@@ -116,8 +116,8 @@ 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.
+- [`dot_config/zsh/rc.d/30-options.zsh.tmpl`](../../defaults/dot_config/zsh/rc.d/30-options.zsh.tmpl) — the deferred-compinit logic.
+- [`run_onchange_after_zcompile-completions.sh.tmpl`](../../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

@@ -44,7 +44,7 @@ matches and emits standard `lcov.info` that Codecov ingests natively.
 | Surface | What runs |
 |---|---|
 | **PR + push to master** | `.github/workflows/coverage.yml` → `Coverage / kcov` job → uploads lcov.info to Codecov and fails the build below `MIN_COVERAGE_PCT` (currently `0`, ratcheted up each slice). |
-| **Local dev** | `bash scripts/ci/run-coverage.sh` — works on Linux + macOS (xtrace is a bash primitive, no platform tools needed). |
+| **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. |
 
 ## The current floor
@@ -52,8 +52,8 @@ matches and emits standard `lcov.info` that Codecov ingests natively.
 `MIN_COVERAGE_PCT=0` 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). Each subsequent slice raises the floor by ~10–15
-percentage points until the target of ≥95% is reached.
+across 231 files). Successive slices raised it; the current measured
+value sits at **~47%**.
 
 To tighten:
 
@@ -64,10 +64,44 @@ To tighten:
    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. After working through
+all six slices, the achievable ceiling with xtrace-only instrumentation
+is closer to **~50%** on this codebase. The remaining gap is structural,
+not aspirational:
+
+- **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 scripts/ci/run-coverage.sh   # Linux or macOS
+bash tools/ci/run-coverage.sh   # Linux or macOS
 
 # Output:
 #   coverage/traces/<file>.trace  — per-test xtrace logs
@@ -125,7 +159,7 @@ threshold to get two independent signals.
 
 ## Excluded paths
 
-`scripts/ci/run-coverage.sh` excludes:
+`tools/ci/run-coverage.sh` excludes:
 
 - `tests/**` itself (don't measure coverage of the tests).
 - `.git/`, `node_modules/`.
@@ -142,7 +176,7 @@ 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).
-- [`scripts/ci/run-coverage.sh`](../../scripts/ci/run-coverage.sh).
+- [`tools/ci/run-coverage.sh`](../../tools/ci/run-coverage.sh).
 - [`.github/workflows/coverage.yml`](../../.github/workflows/coverage.yml).
 - Issue [#856](https://github.com/sebastienrousseau/dotfiles/issues/856) (closed) /
   [#883](https://github.com/sebastienrousseau/dotfiles/issues/883) (coverage roadmap).