@sebastienrousseau/dotfiles 0.2.499 → 0.2.500

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`

package/docs/operations/OPERATIONS.md

@@ -0,0 +1,164 @@
+# Operations
+
+Core workflows for keeping your dotfiles running across platforms.
+
+---
+
+## Platforms
+
+### macOS
+
+**Primary manager**: `Homebrew`
+
+- **Update**:
+  ```bash
+  chezmoi update
+  ```
+  This runs `brew bundle install` behind the scenes to reconcile against the declared Brewfiles.
+- **Permission issues**: `sudo chown -R $(whoami) $(brew --prefix)/*`
+- **Drift**: Run `brew bundle cleanup` to remove unmanaged packages.
+
+### Linux (Debian, Ubuntu, Kali)
+
+**Primary manager**: `apt-get` / `snap`
+
+- **Update**:
+  ```bash
+  sudo apt update && sudo apt upgrade -y
+  chezmoi update
+  ```
+  On Linux, `chezmoi` focuses on configuration. Package updates work best through the OS package manager to avoid `sudo` conflicts.
+- **Font issues**: If icons are missing, run `./install/provision/run_onchange_50-install-fonts.sh.tmpl` manually via `chezmoi apply` or source directly with `bash`.
+
+### Windows (WSL2)
+
+**Primary manager**: `apt-get` (inside WSL)
+
+- **Update**: Same as Linux.
+- **Clipboard**: Dotfiles configures `win32yank.exe` automatically for clipboard sharing.
+- **Performance**: Keep project files inside the Linux filesystem (`~/projects`), not in `/mnt/c/`, for dramatically better IO.
+
+---
+
+## Workflows
+
+### Apply changes
+
+After editing any config file:
+
+```bash
+dot apply
+```
+
+Triggers `dot_zshrc` reload and audit logging.
+
+### Upgrade-safe apply (recommended)
+
+```bash
+git pull
+DOTFILES_NONINTERACTIVE=1 dot apply --force
+dot doctor
+```
+
+`dot apply` includes post-apply checks that:
+- Remove stale read-only zsh cache files (`~/.config/shell/*.zwc`, `~/.config/zsh/**/*.zwc`)
+- Validate that `dot` resolves to `~/.local/bin/dot` in a fresh login shell
+
+Finish by reloading your session (`exec zsh`) or restarting the terminal.
+
+### Async updates
+
+Run updates in the background; you'll get a status banner on the next shell launch:
+
+```bash
+dot update --async
+```
+
+### Roll back
+
+If an update breaks your setup:
+
+```bash
+cd ~/.dotfiles
+git reset --hard HEAD@{1}
+chezmoi apply
+```
+
+### Offline / air-gapped mode
+
+```bash
+# 1. On a connected machine, bundle your setup:
+dot bundle ~/Downloads
+
+# 2. Transfer the archive to the offline machine, then:
+tar --zstd -xf dotfiles_offline_bundle_*.tar.zst -P
+cd ~/.dotfiles
+./install.sh --force
+```
+
+### Pre-warm caches
+
+Regenerate all tool caches to eliminate shell startup latency:
+
+```bash
+dot prewarm
+```
+
+### Debug
+
+If something's slow or broken:
+
+1. **Check health**:
+   ```bash
+   dot doctor
+   dot health --fix
+   ```
+2. **Smoke test**:
+   ```bash
+   dot smoke-test
+   ```
+3. **Scorecard**:
+   ```bash
+   dot scorecard
+   ```
+4. **Chaos testing (self-healing)**:
+   ```bash
+   dot chaos --force
+   dot heal --force
+   ```
+5. **Startup profiling**:
+   ```bash
+   dot perf --profile
+   ```
+6. **Post-merge verification**:
+   ```bash
+   dot verify
+   ```
+7. **Inspect alias behavior**:
+   ```bash
+   dot aliases list
+   dot aliases why dprune
+   DOTFILES_ALIAS_POLICY=strict bash ~/.dotfiles/scripts/diagnostics/alias-governance.sh
+   ```
+8. **Verbose mode**:
+   ```bash
+   DOTFILES_DEBUG=1 dot apply
+   ```
+
+### Safety flags
+
+Destructive aliases are disabled by default. Enable only when needed:
+
+```bash
+export DOTFILES_ENABLE_DANGEROUS_ALIASES=1
+```
+
+### Tiered alias loading
+
+Core aliases load eagerly. Ecosystem aliases are lazy-loaded and can be filtered:
+
+```bash
+export DOTFILES_ALIAS_ECOSYSTEMS=python,node
+```
+
+Valid ecosystem tags: `python`, `node`, `rust`, `network`, `legacy`.

package/docs/operations/RELIABILITY.md

@@ -0,0 +1,116 @@
+# Reliability
+
+## Reliability scorecard
+
+- Unit coverage: 100% module mapping target, enforced by `tests/framework/module_coverage.sh`
+- Integration depth: 11 integration test files in `tests/integration/`
+- Regression automation: 436 discovered test files and 2149 named tests in the current baseline
+
+## Coverage gap map
+
+| Module | Missing path | Risk level | Proposed test case |
+| :--- | :--- | :--- | :--- |
+| `scripts/qa/reliability-audit.sh` | Quick mode and integration mode branch handling | Closed | Covered by `tests/unit/misc/test_qa_reliability_behaviour.sh` |
+| `scripts/git-hooks/pre-push` | Audit command failure path | Closed | Covered by `tests/unit/misc/test_git_hooks_pre_push_behaviour.sh` |
+| `tests/framework/module_coverage.sh` | False-positive module matches | Closed | Covered by `tests/unit/misc/test_module_coverage_behaviour.sh` |
+| `examples/*.sh` | Drift between examples and real commands | Closed | Examples execute in CI through `Examples Contract` and `validate-examples.sh` |
+
+## Integration boundaries
+
+```mermaid
+flowchart LR
+  Dev[Developer] --> Hook[pre-push hook]
+  Hook --> Audit[reliability-audit.sh]
+  Audit --> Syntax[Shell syntax gate]
+  Audit --> Unit[Unit suite]
+  Audit --> Coverage[Module coverage]
+  Audit --> Examples[Example validation]
+  Audit --> WSL[WSL contract]
+  Audit --> Integration[Integration suite]
+  Integration --> Repo[Dotfiles workflows]
+  WSL --> Repo
+```
+
+```mermaid
+sequenceDiagram
+  participant Dev as Developer
+  participant Git as Git client
+  participant Hook as pre-push
+  participant Audit as reliability-audit.sh
+  participant Suite as tests/framework/test_runner.sh
+  participant Cov as module_coverage.sh
+  participant Ex as validate-examples.sh
+  participant WSL as wsl-contract.sh
+
+  Dev->>Git: git push
+  Git->>Hook: invoke pre-push
+  Hook->>Hook: verify signed commits
+  Hook->>Audit: run quick gate
+  Audit->>Suite: run unit suite
+  Audit->>Cov: enforce 100% module mapping
+  Audit->>Ex: execute examples
+  Audit->>WSL: verify WSL parity contract
+  Ex-->>Audit: pass
+  Cov-->>Audit: pass
+  WSL-->>Audit: pass
+  Suite-->>Audit: pass
+  Audit-->>Hook: pass
+  Hook-->>Git: allow push
+```
+
+## CI gate
+
+```yaml
+name: Reliability Gate
+
+on:
+  pull_request:
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+jobs:
+  reliability:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v6
+      - name: Reliability audit
+        run: bash ./scripts/qa/reliability-audit.sh --with-integration
+
+  examples-contract:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Validate executable examples
+        run: bash ./scripts/qa/validate-examples.sh
+
+  wsl-contract:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Validate WSL parity contract
+        run: bash ./scripts/qa/wsl-contract.sh
+
+  reliability-summary:
+    needs: [reliability, examples-contract, wsl-contract]
+    runs-on: ubuntu-latest
+```
+
+## Functional examples
+
+- `examples/example-test-suite.sh`: Runs a focused unit slice.
+- `examples/example-coverage-gate.sh`: Runs the module coverage contract.
+- `examples/example-git-hooks.sh`: Shows the local hook entrypoints.
+- `examples/example-platform-contract.sh`: Shows the platform and host contract across macOS, Linux, and WSL.
+
+## Local guardrail
+
+`make test` is the canonical reliability command. It runs syntax checks, unit tests, module coverage, executable examples, and integration tests.
+
+For a lightweight repository-wide snapshot, run `bash ./scripts/qa/coverage-baseline.sh --with-module-coverage`.
+
+Core internal behaviors are traced through `bash ./scripts/qa/traceability-coverage.sh`.