@sebastienrousseau/dotfiles 0.2.499 → 0.2.501

package/docs/operations/MIGRATION.md

@@ -0,0 +1,109 @@
+---
+render_with_liquid: false
+---
+
+# 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.501 (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.500
+
+- 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.497
+
+- Theme system with Catppuccin integration
+- Linux desktop parity (Niri, Waybar, Fuzzel)
+- AI tooling expansion (Kiro, OpenCode)
+- Coverage contracts and QA docs
+
+### v0.2.496
+
+- Verified chezmoi installer
+- Shell startup optimization
+- Property-based tests
+
+## Breaking Changes
+
+If you are upgrading from v0.2.501 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.501 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,188 @@
+---
+render_with_liquid: false
+---
+
+# 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/PERFORMANCE.md

@@ -0,0 +1,133 @@
+---
+render_with_liquid: false
+---
+
+# Performance — Budgets, Baselines, Regression Detection
+
+This page documents the per-shell startup budget, the baseline
+lifecycle, and the regression-alert pipeline. Managed under
+[#863](https://github.com/sebastienrousseau/dotfiles/issues/863).
+
+## Targets
+
+| Shell | Target (mean ms) | Override env var |
+|---|---|---|
+| **zsh** | 250 | `DOTFILES_PERF_TARGET_ZSH_MS` |
+| **bash** | 60 | `DOTFILES_PERF_TARGET_BASH_MS` |
+| **fish** | 200 | `DOTFILES_PERF_TARGET_FISH_MS` |
+| **nu** | 500 | `DOTFILES_PERF_TARGET_NU_MS` |
+| **pwsh** | 600 | `DOTFILES_PERF_TARGET_PWSH_MS` |
+
+`dot perf` measures every installed shell and flags any whose mean
+exceeds its target. The numbers come from
+[`scripts/diagnostics/perf.sh`](../../scripts/diagnostics/perf.sh) —
+warm-up + 3 runs by default.
+
+## The baseline
+
+`$XDG_CACHE_HOME/dotfiles/perf-baseline.json` records the per-shell
+means at a known-good point in time. The file is a JSON object:
+
+```json
+{
+  "recorded_at": "2026-05-13T00:00:00Z",
+  "regression_pct": 10,
+  "shells": {
+    "zsh": 41,
+    "bash": 28,
+    "fish": 190
+  }
+}
+```
+
+### Recording a baseline
+
+```bash
+dot perf --baseline                 # all installed shells
+dot perf --baseline --shell zsh     # just one shell
+```
+
+Do this after:
+
+- A fresh chezmoi apply on a new machine.
+- Any deliberate startup-cost change (deferred-load PRs, new plugin).
+- A `mise install` that bumps a hot-path tool's version.
+
+### Regression detection
+
+Every subsequent `dot perf` invocation compares the current
+measurement against the baseline. When any shell exceeds the
+baseline by more than `DOTFILES_PERF_REGRESSION_PCT` (default 10%),
+the run reports under a "Baseline regressions" section. JSON output
+includes a `regressions: [...]` array and a `regression_count`
+counter so dashboards can alert.
+
+```bash
+dot perf                            # warns on regression
+dot perf --no-baseline-check        # skip the comparison entirely
+DOTFILES_PERF_REGRESSION_PCT=5 dot perf   # tighter threshold
+```
+
+## Per-tool timings
+
+`_cached_eval` (the zsh/fish primitive that caches expensive tool
+init like `starship init zsh`) writes one JSONL row per call to
+`$XDG_STATE_HOME/dotfiles/eval-timings.jsonl` when
+`EVALCACHE_TIMING=1` is set in the environment. Aggregating that log
+gives a per-tool breakdown of where startup time goes.
+
+```bash
+EVALCACHE_TIMING=1 zsh -i -c exit    # generate data
+dot perf --by-tool                   # see the aggregation
+dot perf --reset                     # clear the log
+```
+
+The aggregator reports `count / total / mean / p50 / p95 / p99`
+per `_cached_eval` label. P95 + P99 surface the tail-latency cases
+that mean alone misses (e.g. a cache miss after a tool upgrade
+spiking from 5ms steady-state to 200ms once).
+
+## `dot doctor` Performance section
+
+`dot doctor` surfaces (when each data source is available):
+
+- Whether `_cached_eval`'s on-disk tool caches are fresh vs stale
+  for mise, starship, zoxide, atuin, fzf, direnv.
+- Any installed slow-init tools NOT yet wrapped in `_cached_eval`
+  (nvm, fnm, pyenv, pnpm, …).
+- Hyperfine-measured startup latency vs target.
+- Baseline age + top-3 slowest tools from the EVALCACHE_TIMING log.
+
+## CI workflow
+
+[`.github/workflows/perf-baseline.yml`](../../.github/workflows/perf-baseline.yml)
+runs weekly on Sunday at 03:00 UTC on `ubuntu-latest`. It:
+
+1. Restores the previous week's baseline from a workflow artifact.
+2. Runs `dot perf --json` against the freshly-applied dotfiles.
+3. Compares current vs restored baseline; opens (or comments on) a
+   tracking issue if any shell regressed by >10%.
+4. Uploads the new measurement as the next week's restore source.
+
+The CI workflow always runs against the same `ubuntu-latest` image
+so the comparison is machine-stable; per-developer baselines live on
+each developer's box and aren't synced.
+
+## Adjusting the budget
+
+Per-shell targets live in
+[`scripts/diagnostics/perf.sh`](../../scripts/diagnostics/perf.sh)
+under `shell_target_for()`. Bumping a target should always come with:
+
+- A commit-message rationale explaining why slower is acceptable
+  (e.g. "added a required Carapace completion at startup").
+- A new baseline recording (`dot perf --baseline`).
+- A note here under "Targets" with the new value.
+
+## References
+
+- [`scripts/diagnostics/perf.sh`](../../scripts/diagnostics/perf.sh)
+- [`tests/unit/diagnostics/test_perf_percentiles.sh`](../../tests/unit/diagnostics/test_perf_percentiles.sh) — percentile math contract
+- [`.github/workflows/perf-baseline.yml`](../../.github/workflows/perf-baseline.yml)
+- ADR-002 (Shell Performance Optimization)
+- Issue [#863](https://github.com/sebastienrousseau/dotfiles/issues/863)

package/docs/operations/RELIABILITY.md

@@ -0,0 +1,122 @@
+---
+render_with_liquid: false
+---
+{% raw %}
+
+# 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`.
+{% endraw %}