@sebastienrousseau/dotfiles 0.2.481 → 0.2.500

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

@@ -0,0 +1,54 @@
+# 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.500.* <https://github.com/sebastienrousseau/dotfiles>

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

@@ -0,0 +1,34 @@
+# 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.500"
+
+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,58 @@
+# 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,164 @@
+# 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,39 @@
+# 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/MAINTENANCE.md

@@ -0,0 +1,59 @@
+# Dotfiles Maintenance Runbook
+
+This runbook captures recovery and release maintenance operations for this repository.
+
+## Signed History Recovery (February 19, 2026)
+
+**Purpose:** Recover from strict signature enforcement failures caused by legacy/non-compliant commit history.
+
+**When to use:**
+
+- Pushes are blocked by signature policy on historical commits.
+- Merge ancestry contains commits that can't be validated by the current principal/key policy.
+
+**Procedure:**
+
+1. Create a backup ref for current `master`.
+2. Build a rewritten signed baseline commit from the current tree.
+3. Push the rewritten branch to remote.
+4. Temporarily allow force-push on `master` protections/rulesets.
+5. Force-update `master` to the rewritten signed baseline.
+6. Disable force-push again immediately.
+7. Re-run CI and verify required checks are green.
+8. Repoint the release tag/target as needed.
+
+**Verification commands:**
+
+```bash
+git verify-commit HEAD
+gh run list --workflow ci.yml --branch master --limit 1
+gh release view v0.2.500 --json tagName,targetCommitish,url
+```
+
+## Release Closeout Checklist
+
+For every release update:
+
+1. `master` branch is clean and synced.
+2. CI is green on the release commit.
+3. Annotated release tag points to the intended commit.
+4. GitHub release target is correct (`master` or explicit commit).
+5. Branch protections/rulesets are restored to strict state.
+6. Local apply has completed:
+
+```bash
+CHEZMOI_SOURCE_DIR="$HOME/.dotfiles" ./dot_local/bin/executable_dot apply
+```
+
+## Security Scan Guardrails
+
+We prevent gitleaks historical-scan regressions with:
+
+- Shallow checkout (`fetch-depth: 1`, `fetch-tags: false`) in gitleaks jobs.
+- A workflow-dispatch guard script: `scripts/ci/guard-gitleaks-checkout.sh`.
+
+**Manual verification:**
+
+```bash
+bash scripts/ci/guard-gitleaks-checkout.sh
+```

package/docs/operations/MIGRATION.md

@@ -0,0 +1,101 @@
+# Migration and Upgrade Guide
+
+## How to Upgrade
+
+```bash
+# 1. Pre-upgrade check
+dot doctor
+
+# 2. Pull latest changes
+cd ~/.dotfiles && git pull
+
+# 3. Apply with diagnostics
+dot apply
+
+# 4. Post-upgrade verification
+dot doctor
+```
+
+## Version History
+
+### v0.2.500 (Current)
+- **Wallpaper-driven theme engine** — themes auto-generated from wallpapers via K-Means in CIELAB color space (no hand-crafted themes)
+- **Dynamic HEIC support** — custom wallpapers ship as Apple-compatible single-file dynamic HEIC; macOS auto-switches dark/light
+- **System wallpaper discovery** — pulls themes from `/System/Library/Desktop Pictures/` (macOS) and `/usr/share/backgrounds/` (Linux)
+- **`dot theme rebuild`** — parallel K-Means generation (4 jobs), mtime-based caching, orphan cleanup
+- **WCAG AAA enforcement** — all generated themes pass 7:1 contrast for fg/bg, accent_text/accent, c15/bg
+- **macOS accent from wallpaper hue** — `dot-theme-sync` reads `macos_accent` from themes.toml and forces UI refresh
+- **HEIC → PNG auto-conversion** on Linux for non-HEIC-aware desktops
+- **Build artifact redirection** — Cargo, Go, pip, uv, Zig caches → `/tmp/builds/` (cleared on reboot)
+- **CI dedup** — `ci-enforced.yml` reuses `reusable-shell-lint.yml` and `reusable-test-suite.yml`
+
+### v0.2.499
+- Added AI CLIs: Autohand Code, Mistral Vibe, Qwen Code, ZAI
+- Removed Cline CLI (broken upstream dependency)
+- Interactive mise installer for missing AI providers
+- Mise-first provisioning for all AI tools
+- User extension points: rc.d.local, modules.d, custom dot commands
+- SSH config hardening template
+- Ghostty and WezTerm terminal configs
+- Modern CLI tools: delta, fd, dust, bottom, lazygit, lazydocker, tldr
+- Auto-prewarm after dot apply
+- Expanded Atuin history filters
+
+### v0.2.498
+- Theme system with Catppuccin integration
+- Linux desktop parity (Niri, Waybar, Fuzzel)
+- AI tooling expansion (Kiro, OpenCode)
+- Coverage contracts and QA docs
+
+### v0.2.497
+- Verified chezmoi installer
+- Shell startup optimization
+- Property-based tests
+
+## Breaking Changes
+
+If you are upgrading from v0.2.499 or earlier, note these changes:
+
+1. **`themes.toml` is now generated** — do not hand-edit. Run `dot theme rebuild` to regenerate from wallpapers
+2. **Theme names changed** — old hand-crafted names (e.g. `catppuccin-mocha`, `macos-tahoe-dark` with hardcoded palettes) are replaced by wallpaper-derived names. The picker only shows paired wallpaper themes.
+3. **Wallpaper format** — custom wallpapers should be dynamic HEIC (single file, both appearances). Use `bash scripts/theme/merge-wallpaper.sh` to merge separate dark/light pairs.
+4. **Build caches relocated** — Cargo/Go/pip/uv/Zig now write to `/tmp/builds/`. Restart your shell after upgrade so `mise [env]` picks up the new paths.
+
+If you are upgrading from v0.2.498 or earlier:
+
+1. **Cline CLI removed** — if you used `dot cline`, switch to a different AI CLI
+2. **AI tools now install through mise** — run `mise install` to set up AI providers
+3. **SSH config hardening** — check `~/.ssh/config` after apply, as it may change your current settings
+
+## Rollback
+
+If something goes wrong after an upgrade:
+
+```bash
+# Quick rollback to previous state
+dot rollback
+
+# Rollback to specific backup
+dot rollback status       # List available backups
+dot rollback rollback-to 3  # Restore backup #3
+
+# Git-based rollback
+cd ~/.dotfiles
+git log --oneline -10     # Find last good commit
+git reset --hard HEAD~1   # Reset to previous commit
+dot apply                 # Re-apply
+```
+
+## Before You Upgrade
+
+- [ ] Run `dot doctor` — make sure everything is healthy
+- [ ] Run `dot diff` — review any pending changes
+- [ ] Back up custom configs: `dot rollback backup`
+- [ ] Read CHANGELOG.md for breaking changes
+
+## After You Upgrade
+
+- [ ] Run `dot doctor` — make sure the upgrade worked
+- [ ] Run `dot prewarm` — rebuild shell caches
+- [ ] Restart your shell: `exec zsh`
+- [ ] Test AI tools: `dot ai`