@sebastienrousseau/dotfiles 0.2.519 → 0.2.521

package/docs/operations/MAINTENANCE.md

@@ -1,63 +0,0 @@
----
-render_with_liquid: false
----
-
-# 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 `main`.
-2. Build a rewritten signed baseline commit from the current tree.
-3. Push the rewritten branch to remote.
-4. Temporarily allow force-push on `main` protections/rulesets.
-5. Force-update `main` 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 main --limit 1
-gh release view v0.2.501 --json tagName,targetCommitish,url
-```
-
-## Release Closeout Checklist
-
-For every release update:
-
-1. `main` 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 (`main` or explicit commit).
-5. Branch protections/rulesets are restored to strict state.
-6. Local apply has completed:
-
-```bash
-CHEZMOI_SOURCE_DIR="$HOME/.dotfiles" ./bin/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: `tools/ci/guard-gitleaks-checkout.sh`.
-
-**Manual verification:**
-
-```bash
-bash tools/ci/guard-gitleaks-checkout.sh
-```

package/docs/operations/MANIFEST.md

@@ -1,127 +0,0 @@
----
-title: "Workstation Environment Manifest"
-date: 2026-05-17
----
-
-# Workstation Environment Manifest
-
-`dot env emit` produces a portable, schema-validated record of
-"what is installed on this machine" — the canonical input that
-downstream tooling consumes.
-
-## Schema
-
-[`docs/schema/dot-env-v1.json`](../schema/dot-env-v1.json) is a
-JSON Schema 2020-12 file. Validate any manifest against it with:
-
-```sh
-dot env emit | jsonschema -i /dev/stdin docs/schema/dot-env-v1.json
-# or
-dot env emit | check-jsonschema --schemafile docs/schema/dot-env-v1.json /dev/stdin
-```
-
-(`jsonschema` from the `jsonschema` PyPI package; `check-jsonschema`
-from `python-jsonschema/check-jsonschema`. Either works.)
-
-## Quick reference
-
-```sh
-dot env emit                              # canonical JSON to stdout
-dot env emit --format ndjson              # one tool per line, greppable
-dot env emit --output /tmp/env.json       # atomic file write
-dot env emit --compact                    # one-line JSON
-dot env emit --help                       # flags + examples
-```
-
-Example output (truncated):
-
-```json
-{
-  "schema_version": "https://sebastienrousseau.github.io/dotfiles/schema/dot-env-v1.json",
-  "manifest_version": "1.0.0",
-  "emitted_at": "2026-05-17T10:22:46Z",
-  "emitter": {
-    "name": "dot env emit",
-    "version": "0.2.503",
-    "repo": "github.com/sebastienrousseau/dotfiles"
-  },
-  "host": {
-    "hostname": "rousseau-mbp-m1",
-    "os": "Darwin",
-    "arch": "arm64"
-  },
-  "tools": [
-    {
-      "name": "node",
-      "version": "24.14.0",
-      "source": "/Users/seb/.dotfiles/mise.toml",
-      "source_type": "mise.toml",
-      "requested_version": "24.14.0",
-      "install_path": "/Users/seb/.local/share/mise/installs/node/24.14.0",
-      "active": true
-    },
-    ...
-  ]
-}
-```
-
-## Why this exists
-
-R3 §7.4 strategic-reversal call: **ship `dot env emit` BEFORE
-`dot fleet apply --attest`**. Three independent forces converge on
-a 2026-09-17 / 2026-09-11 window:
-
-1. **AgentSpec / AAIF** public deadline at AGNTCon Amsterdam
-   2026-09-17. First-mover with the canonical "one signed
-   manifest → AGENTS.md, agent.yaml, devcontainer-feature.json,
-   mise.toml, Brewfile, flake.nix, in-toto subject list"
-   generator owns the reference implementation.
-2. **EU CRA SBOM reporting** binding 2026-09-11. A v1 manifest
-   per workstation feeds the "demonstrate vulnerability response"
-   story for any EU procurement team.
-3. **dotbot v3.5.0's `workflow.yaml`** is 80% of the way to
-   AgentEnv parity. The window before they generate the same
-   manifest is measured in weeks.
-
-## Downstream consumers (planned)
-
-The v1 manifest is the source-of-truth that subsequent emitters
-will re-render. Each emitter is a single jq filter from the v1
-shape:
-
-| Target format | Use case | Status |
-|---|---|---|
-| `AGENTS.md` | Cross-harness AI agent context | shipped (`dot agents render`); will be re-pointed at the v1 manifest in v0.2.504 |
-| `devcontainer-feature.json` | Reproducible cloud-IDE setup | planned (v0.2.504) |
-| `mise.toml` | Round-trip: re-create the same install set on a fresh host | planned |
-| `Brewfile` | Hand off to a Homebrew-managed Mac | planned |
-| `flake.nix` | Nix reproducibility | planned (input to nix-shell) |
-| `in-toto subject list` | SLSA attestation subject array | planned (`dot fleet apply --attest`) |
-| `CycloneDX SBOM` | Compliance reporting (EU CRA) | planned (v0.2.504; per-artifact attestation closes R3-N7) |
-
-The schema is intentionally minimal — `dot env emit` records *what
-is installed*, not *what is desired* or *what is approved*. Downstream
-emitters add policy / approval / risk-score columns as they need
-them.
-
-## CI usage
-
-```yaml
-- name: Snapshot environment manifest
-  run: |
-    dot env emit --output env.json
-    # Attest the manifest as part of the next release
-    cosign sign-blob --yes --output-signature env.json.sig \
-      --output-certificate env.json.pem env.json
-```
-
-The signed manifest goes into the release alongside the SBOM —
-together they let any consumer answer "what software was on the
-runner that produced this release" and verify it cryptographically.
-
-## See also
-
-- `docs/schema/dot-env-v1.json` — the JSON Schema authoritative spec.
-- `docs/security/VERIFY_RELEASE.md` — three-attestation verification flow this manifest plugs into.
-- `docs/operations/HARD_AUDIT_2026.md` §7.4 — strategic-reversal record.
-- `docs/operations/ROADMAP_V0_2_503.md` — `dot env emit` was originally deferred to v0.2.504; pulled forward in this PR per user request.

package/docs/operations/MIGRATION.md

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

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

@@ -1,133 +0,0 @@
----
-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`](https://github.com/sebastienrousseau/dotfiles/blob/main/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`](https://github.com/sebastienrousseau/dotfiles/blob/main/.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`](https://github.com/sebastienrousseau/dotfiles/blob/main/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`](https://github.com/sebastienrousseau/dotfiles/blob/main/scripts/diagnostics/perf.sh)
-- [`tests/unit/diagnostics/test_perf_percentiles.sh`](https://github.com/sebastienrousseau/dotfiles/blob/main/tests/unit/diagnostics/test_perf_percentiles.sh) — percentile math contract
-- [`.github/workflows/perf-baseline.yml`](https://github.com/sebastienrousseau/dotfiles/blob/main/.github/workflows/perf-baseline.yml)
-- ADR-002 (Shell Performance Optimization)
-- Issue [#863](https://github.com/sebastienrousseau/dotfiles/issues/863)