@sebastienrousseau/dotfiles 0.2.499 → 0.2.501

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

@@ -0,0 +1,40 @@
+---
+render_with_liquid: false
+---
+
+# Appendix C: Glossary
+
+| Term | Definition |
+|:---|:---|
+| **Age** | Modern file-encryption tool using X25519 + ChaCha20-Poly1305. Stores secrets in the repository encrypted at rest. |
+| **Agent Profile** | A named behaviour template for AI agents (e.g. architect, hardener). Stored in `dot_config/ai/patterns/`. |
+| **ANSI Colors** | The 16 foreground/background color slots (c0 through c15) used by terminal emulators. |
+| **Apple Desktop APR** | XMP metadata in dynamic HEIC wallpapers mapping image indices to light/dark appearance modes. |
+| **Attestation** | Signed JSON document asserting machine identity, policy, tool versions, and Git state at a point in time. |
+| **Baseline (security)** | Reference state used by `detect-secrets` to distinguish new leaks from known acceptable patterns. |
+| **Chaos** | Intentional corruption (`dot chaos`) used to verify `dot heal` recovers to a healthy state. |
+| **Chezmoi** | The templating engine handling per-platform rendering and applying configuration to `$HOME`. |
+| **CIELAB** | Color space designed for perceptual uniformity. Used by the theme engine for K-Means clustering. |
+| **CycloneDX** | SBOM format used by the repository for machine-readable dependency inventories. |
+| **Dank Material Shell (DMS)** | A shell for the Niri Wayland compositor that provides polished theming hooks. |
+| **Drift** | Local changes to managed files that diverge from the source tree. Detected by `dot status`. |
+| **Dynamic HEIC** | Apple's single-file wallpaper format that contains both light and dark variants with appearance metadata. |
+| **Fleet** | Two or more workstations sharing a single `.dotfiles` source repository. |
+| **Gitleaks** | Secret-pattern scanner that blocks commits containing obvious secret patterns. |
+| **Golden Ratio** | 1.618... Used as the target brightness ratio between dark and light theme variants. |
+| **Heal** | The `dot heal` command's action of auto-fixing drift, missing tools, and broken symlinks. |
+| **Idempotent** | Property where running an operation twice has the same result as running it once. |
+| **K-Means** | Clustering algorithm partitioning data into k groups by proximity to centroids. Used for dominant color extraction. |
+| **K-Means++** | Variant of K-Means with smart initialization that reduces sensitivity to random seeding. |
+| **MCP** | Model Context Protocol — standard for connecting AI models to external tools and data. |
+| **Mise** | User-space language and tool version manager. Replaces asdf, nvm, rbenv, pyenv. |
+| **Nix Flakes** | Nix's reproducible-build system. Used for strict repeatability when Mise's approximations aren't enough. |
+| **Niri** | Wayland compositor with scrollable tiling layout. |
+| **Policy Hash** | SHA-256 of the active MCP policy JSON. Included in attestations for drift detection. |
+| **Prewarm** | `dot prewarm` regenerates shell init caches, eliminating slow first-shell startup. |
+| **Profile** | Named collection of settings in `.chezmoidata.toml` selectable via `dot profile`. |
+| **SOPS** | "Secrets OPerationS" — YAML-aware envelope encryption tool that wraps Age (or PGP/AWS KMS). |
+| **SBOM** | Software Bill of Materials — machine-readable dependency list, generated by Syft, scanned by Grype. |
+| **Trust Anchor** | The root public key from which all other trust derives. For `.dotfiles`, the user's SSH ED25519 signing key. |
+| **WCAG AAA** | Web Content Accessibility Guidelines Level AAA — 7:1 text contrast ratio, the highest accessibility tier. |
+| **XDG Base Directory** | Spec defining `~/.config`, `~/.cache`, `~/.local/share`, `~/.local/state` for app data locations. |

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

@@ -0,0 +1,58 @@
+---
+render_with_liquid: false
+---
+
+# Appendix D: Bibliography
+
+Cited works and recommended reading.
+
+## Algorithms
+
+- **MacQueen, J. (1967).** *Some methods for classification and analysis of multivariate observations.* Proceedings of the Fifth Berkeley Symposium on Mathematical Statistics and Probability. — The original K-Means paper.
+- **Arthur, D. & Vassilvitskii, S. (2007).** *K-Means++: The advantages of careful seeding.* ACM-SIAM Symposium on Discrete Algorithms. <https://theory.stanford.edu/~sergei/papers/kMeansPP-soda.pdf>
+- **Heckbert, P. (1982).** *Color image quantization for frame buffer display.* Computer Graphics 16(3). — Median cut algorithm, the alternative to K-Means.
+
+## Color Science
+
+- **CIE (1976).** *Recommendations on uniform color spaces, color-difference equations, psychometric color terms.* Supplement No. 2 to CIE Publication No. 15. — Defines CIELAB.
+- **Lindbloom, B. J.** *RGB/XYZ matrices.* <http://www.brucelindbloom.com/index.html?Eqn_RGB_XYZ_Matrix.html> — sRGB → XYZ conversion reference.
+- **Fairchild, M. D. (2013).** *Color Appearance Models, 3rd Edition.* Wiley. — Comprehensive treatment of perceptual color spaces.
+
+## Accessibility
+
+- **W3C (2023).** *Web Content Accessibility Guidelines (WCAG) 2.2.* <https://www.w3.org/TR/WCAG22/> — Accessibility standards including contrast ratios.
+- **W3C.** *Techniques for WCAG 2.2: G17 Using a contrast ratio of at least 7:1.* <https://www.w3.org/WAI/WCAG22/Techniques/general/G17>
+
+## Cryptography
+
+- **Valsorda, F. (2020).** *age: A simple, modern and secure encryption tool.* <https://age-encryption.org/>
+- **Mozilla.** *SOPS: Secrets OPerationS.* <https://github.com/getsops/sops>
+- **Barnes, R., et al. (2023).** *RFC 9420: The Messaging Layer Security (MLS) Protocol.* — Modern group-key agreement, relevant to multi-recipient encryption.
+
+## Protocols
+
+- **Anthropic.** *Model Context Protocol specification.* <https://modelcontextprotocol.io/>
+- **OpenID Foundation.** *Model Context Protocol A2A (Agent-to-Agent).* — Referenced in `dot_config/dotfiles/agent-card.json`.
+
+## Tools & Systems
+
+- **Twpayne, T.** *chezmoi: Manage your dotfiles across multiple machines.* <https://chezmoi.io>
+- **jdxcode.** *mise: Dev tools, env vars, task runner.* <https://mise.jdx.dev/>
+- **NixOS.** *Nix Flakes.* <https://nixos.wiki/wiki/Flakes>
+- **Microsoft / CycloneDX.** *CycloneDX SBOM specification.* <https://cyclonedx.org/>
+- **Anchore.** *Syft + Grype.* <https://github.com/anchore/syft>, <https://github.com/anchore/grype>
+
+## Shell Performance
+
+- **Yoo, D.** *How to benchmark shell startup time.* <https://web.archive.org/web/2023/https://hermann.blog/benchmark-shell-startup-time>
+- **Zsh manual.** *Startup files: zshenv, zprofile, zshrc.* <https://zsh.sourceforge.io/Doc/Release/Files.html>
+
+## Documentation Systems
+
+- **GNU Stow documentation.** <https://www.gnu.org/software/stow/manual/> — Inspiration for this manual's multi-format publishing model.
+- **Pandoc.** *Universal document converter.* <https://pandoc.org/>
+- **GNU Texinfo.** <https://www.gnu.org/software/texinfo/> — The original GNU documentation system.
+
+## Author
+
+- **Rousseau, S.** *Dotfiles v0.2.501.* <https://github.com/sebastienrousseau/dotfiles>

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

@@ -0,0 +1,38 @@
+---
+render_with_liquid: false
+---
+
+# Appendix E: License
+
+## MIT License
+
+Copyright (c) 2015-2026 Sebastien Rousseau
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+## Third-Party Licenses
+
+This repository references, configures, or wraps many third-party tools. Each tool retains its own license:
+
+| Tool | License |
+|:---|:---|
+| Chezmoi | MIT |
+| Mise | MIT |
+| Nix | LGPL-2.1 |
+| Age | BSD-3-Clause |
+| SOPS | MPL-2.0 |
+| Fish shell | GPL-2.0 |
+| Zsh | Zsh License (MIT-like) |
+| Neovim | Apache-2.0 |
+| ImageMagick | ImageMagick License (Apache-2.0-like) |
+| Pandoc | GPL-2.0+ |
+
+Wallpapers referenced from `/System/Library/Desktop Pictures/` or `/usr/share/backgrounds/` retain their original vendors' licenses (Apple, Microsoft, distribution vendors). They are not redistributed by this repository — they are discovered and processed in place.
+
+## Contributions
+
+Contributions are accepted under the MIT License. By submitting a pull request, you assert that your contribution is your own work (or properly attributed) and that it may be relicensed under MIT.

package/docs/manual/_toc.yml

@@ -0,0 +1,58 @@
+# Master ordering for build-manual.sh
+# 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.501"
+
+sections:
+  - file: 00-introduction.md
+    title: "Introduction"
+
+  - group: "Concepts"
+    prefix: "01-concepts"
+    files:
+      - 01-architecture.md
+      - 02-trust-model.md
+      - 03-theme-engine.md
+      - 04-fleet.md
+      - 05-self-healing.md
+
+  - group: "Tutorials"
+    prefix: "02-tutorials"
+    files:
+      - 01-first-install.md
+      - 02-add-wallpaper.md
+      - 03-create-profile.md
+      - 04-encrypt-secret.md
+      - 05-deploy-fleet.md
+
+  - group: "Reference"
+    prefix: "03-reference"
+    files:
+      - 01-dot-cli.md
+      - 02-config-files.md
+      - 03-environment.md
+      - 04-templates.md
+      - 05-feature-flags.md
+
+  - group: "Cookbook"
+    prefix: "04-cookbook"
+    files:
+      - 01-recipes.md
+      - 02-troubleshooting.md
+      - 03-faq.md
+
+  - group: "Appendices"
+    prefix: "05-appendices"
+    files:
+      - A-platform-matrix.md
+      - B-security-checklist.md
+      - C-glossary.md
+      - D-bibliography.md
+      - E-license.md
+
+  - file: concept-index.md
+    title: "Concept Index"
+
+  - file: command-index.md
+    title: "Command Index"

package/docs/manual/command-index.md

@@ -0,0 +1,62 @@
+---
+render_with_liquid: false
+---
+
+# Command Index
+
+Alphabetical list of `dot` subcommands referenced in the manual.
+
+- `dot agent`
+- `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 attest`
+- `dot fleet diff`
+- `dot fleet sync`
+- `dot fleet`
+- `dot heal`
+- `dot help`
+- `dot learn`
+- `dot lint`
+- `dot load-bench`
+- `dot manual text`
+- `dot manual`
+- `dot mcp --strict`
+- `dot mcp`
+- `dot metrics`
+- `dot mode`
+- `dot packages`
+- `dot perf`
+- `dot prewarm`
+- `dot profile`
+- `dot rollback`
+- `dot score`
+- `dot secrets rotate`
+- `dot secrets`
+- `dot status`
+- `dot sync`
+- `dot theme list`
+- `dot theme rebuild`
+- `dot theme toggle`
+- `dot theme`
+- `dot tune`
+- `dot update`
+- `dot upgrade`
+- `dot verify --security`
+- `dot verify`
+- `dot version`

package/docs/manual/concept-index.md

@@ -0,0 +1,168 @@
+---
+render_with_liquid: false
+---
+
+# Concept Index
+
+Alphabetical list of concepts covered in the manual.
+
+- Accessibility
+- Adding a New Flag
+- Agent Policy Enforcement
+- AI & Agents
+- Algorithms
+- Apply / Sync
+- Attestation
+- Author
+- Auto-Populated
+- Bibliography
+- Build Artifacts
+- Built-in Chezmoi Functions
+- Built-in Chezmoi Variables
+- Cache Files
+- Caching
+- Changing Presets on an Existing Host
+- Checking Active Flags
+- CI
+- CI-Level Gates
+- CI-Specific
+- Color Science
+- Configuration
+- Contributions
+- Cross-Host Trust
+- Cryptography
+- Daily Use
+- Data Flow
+- Design Principles
+- Development
+- Diagnostics
+- Documentation Systems
+- Drift Detection
+- Dynamic HEIC (Apple Appearance Metadata)
+- Environment Variables
+- Example: Font Size by Preset
+- Example: Platform × Preset
+- Example: Using Theme in Ghostty Config
+- Exit Codes
+- Feature Matrix
+- Flag Catalogue
+- Flag Deprecation
+- Fleet
+- Fleet Attestation
+- Fleet Deployment Workflow
+- Fleet Operational Commands
+- Fleet Trust Propagation
+- From `.chezmoidata.toml`
+- From `.chezmoidata/hardware.toml`
+- From `.chezmoidata/themes.toml`
+- From Feature Flags
+- Gates Enforced by CI
+- General
+- Getting More Help
+- Global Flags
+- Global Flags (`.chezmoidata.toml`)
+- Hardware Presets
+- Helper Templates (in `.chezmoitemplates/`)
+- Identity and Signing
+- Incident Response
+- Inspect & Repair
+- Installation
+- Installation & Update
+- Invocation
+- Limitations
+- Listing Known Presets
+- Log Files
+- Machine-Scoped Secrets
+- Manual
+- MIT License
+- Next
+- Observability
+- Ongoing (monthly)
+- Ongoing (quarterly)
+- Operational Rules
+- Option A: Drop a Static Image
+- Option B: Dynamic HEIC (Recommended)
+- Option C: Golden Ratio Brightness (Advanced)
+- Option D: Install System Wallpapers (Already-Available)
+- Optional Binaries (installed by Mise on first apply)
+- Per-Machine Profiles
+- Per-Preset Overrides (`.chezmoidata/hardware.toml`)
+- Performance
+- Philosophy
+- Post-Install
+- Pre-Install
+- Prerequisites
+- Principles
+- Protocols
+- Read by Tools
+- Recovery
+- Reference
+- Required Binaries
+- Scenario
+- Secret-Related
+- Secrets
+- See Also
+- Shell Performance
+- Single Source, Many Hosts
+- Source Repository
+- Start Here
+- Startup Order
+- Startup Performance Model
+- Step 1: Choose or Create a Preset
+- Step 1: Generate an Age Key (First Time Only)
+- Step 1: Per-Host Install
+- Step 1: Run the Installer
+- Step 2: Choose Encryption Method
+- Step 2: Exchange Signing Keys
+- Step 2: Select the Preset for This Host
+- Step 2: Verify
+- Step 3: Reference the Preset in Templates
+- Step 3: Share the Age Key (for Shared Secrets)
+- Step 3: Take the Tour
+- Step 3A: Chezmoi-Encrypted File
+- Step 3B: SOPS-Encrypted YAML
+- Step 4: Add a New Preset
+- Step 4: Customize
+- Step 4: Reference the Secret in a Template
+- Step 4: Verify Fleet Alignment
+- Step 5: Add Your Identity
+- Step 5: Commit and Verify
+- Step 5: Per-Host Customization
+- Step 5: Per-Preset Feature Flags
+- Step 6: First Theme Switch
+- Step 6: Fleet-Wide Updates
+- Step 6: Multi-Recipient (Fleet)
+- Step 7: Rotate a Compromised Key
+- Step 7: Secrets Rotation
+- Step 8: Decommission a Host
+- Summary
+- Supported Architectures
+- Supported Platforms
+- Supported Shells
+- Template Testing
+- Tested CI Environments
+- The Four Subsystems
+- The Pipeline
+- The Self-Healing Loop
+- The Threat Model
+- The Why
+- Theme
+- Theme Application
+- Themes
+- Third-Party Licenses
+- Threat Model Summary
+- Tools & Systems
+- Troubleshooting
+- Troubleshooting Community
+- Trust Boundaries
+- Unsetting
+- User-Owned Configuration
+- User-Settable
+- Using a Flag in a Template
+- Validation in CI
+- Verified Files
+- Verifying No Plaintext Leaks
+- Verifying the Result
+- Wallpaper Discovery
+- What Got Installed
+- When to Use a Profile

package/docs/operations/ATTESTATION.md

@@ -0,0 +1,44 @@
+---
+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

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