@sebastienrousseau/dotfiles 0.2.481 → 0.2.500

package/docs/manual/01-concepts/03-theme-engine.md

@@ -0,0 +1,182 @@
+# The Theme Engine
+
+`.dotfiles` generates terminal color palettes directly from wallpaper images. There are no hand-crafted themes — dominant colors are extracted via K-Means clustering in CIELAB color space, mapped to ANSI slots, and enforced to WCAG AAA contrast.
+
+This chapter explains the pipeline end to end.
+
+## The Why
+
+Hand-crafted themes are expensive to maintain and constrain the user to a fixed palette. Wallpaper-driven themes:
+
+- **Adapt to any wallpaper** — drop a new image, run `dot theme rebuild`, get a new theme
+- **Guarantee contrast** — WCAG AAA is enforced algorithmically, not by taste
+- **Avoid IP issues** — the engine never redistributes Apple/Microsoft wallpapers; it works with whatever is already on the user's system
+- **Produce matched pairs** — every wallpaper yields a dark and light variant with a golden-ratio brightness relationship
+
+## The Pipeline
+
+```mermaid
+graph LR
+    A[Wallpaper image<br/>any format] --> B[ImageMagick<br/>downsample + RGB extract]
+    B --> C[Random subsample<br/>2000 pixels]
+    C --> D[sRGB → CIE XYZ → CIELAB]
+    D --> E[K-Means++ clustering<br/>k=8, 3 runs, best inertia]
+    E --> F[Map clusters to<br/>ANSI hue slots]
+    F --> G[Enforce WCAG AAA<br/>contrast adjustments]
+    G --> H[Generate theme TOML<br/>16 ANSI + UI + app mappings]
+```
+
+### Stage 1 — Pixel Extraction
+
+`ImageMagick` resizes the wallpaper to 80×80 maximum dimension (preserving aspect ratio) and emits pixel-by-pixel text output:
+
+```sh
+magick input.heic -resize 80x80\> -depth 8 txt:-
+```
+
+At 80×80 the image has ~6,400 pixels. For dynamic HEIC files (`image.heic[0]`, `image.heic[1]`), each frame is processed independently.
+
+### Stage 2 — Subsampling
+
+2,000 pixels are sampled uniformly from the downsampled image using a seeded PRNG (`random.Random(42)`). This gives a reproducible run and keeps K-Means iteration fast.
+
+### Stage 3 — Color Space Conversion
+
+Each RGB triplet is converted:
+
+1. **sRGB → linear RGB** — gamma correction using the sRGB companding curve
+2. **Linear RGB → CIE XYZ** — D65 illuminant, matrix multiplication
+3. **CIE XYZ → CIELAB** — nonlinear transform; distances in Lab approximate human perception
+
+Why CIELAB? In RGB, a "distance" of 30 between two colors might look identical to one eye and drastically different to another. In CIELAB, Δ*E* distances are perceptually uniform — a Δ*E* of 2 is the threshold for "just noticeable different" regardless of which axis moves.
+
+### Stage 4 — K-Means Clustering
+
+**K-Means++** initialization places initial centroids spread across the color space (reducing "bad seed" failures). The algorithm:
+
+1. Pick one random pixel as centroid 1
+2. For centroids 2..k, pick a pixel with probability proportional to D(x)² (squared distance to nearest existing centroid)
+3. Iterate: assign each pixel to its nearest centroid, recompute centroid as mean of assigned pixels
+4. Stop when assignments stabilize or max iterations reached
+
+We run the algorithm 3 times with different seeds and keep the clustering with lowest inertia (sum of squared distances from each pixel to its centroid). This avoids local minima without the cost of more runs.
+
+### Stage 5 — ANSI Hue Mapping
+
+The 6 chromatic ANSI slots (red, green, yellow, blue, magenta, cyan) are assigned target hue angles:
+
+| ANSI Slot | Target Hue (degrees) |
+|:---|---:|
+| red | 30 |
+| yellow | 95 |
+| green | 145 |
+| cyan | 210 |
+| blue | 275 |
+| magenta | 330 |
+
+For each slot, the engine picks the most chromatic cluster whose hue is nearest to the target. If no cluster is close enough, the color is synthesized by projecting the accent chroma onto the target hue angle.
+
+Structural slots (`c0`/black, `c7`/white, `c8`, `c15`) are computed from the background Lab with fixed lightness offsets — they exist to provide the required contrast ratios, not to carry hue information.
+
+### Stage 6 — WCAG AAA Contrast Enforcement
+
+Every color pair is checked and adjusted:
+
+| Pair | Minimum Ratio |
+|:---|---:|
+| `fg` / `bg` | 7:1 |
+| `accent_text` / `accent` | 7:1 |
+| `c15` / `bg` | 7:1 |
+| `fg` / `sel_bg` | 4.5:1 |
+| `c8` / `bg` | 2.5:1 |
+| `c0` / `bg` | 1.5:1 |
+| `panel` / `bg` | 1.03-2.0 (bounded) |
+| `border` / `bg` | 1.08-3.5 (bounded) |
+
+For the accent, the engine darkens in Lab space until white text has 7:1 contrast. For fg and bright ANSI colors, lightness is adjusted until the target ratio is met. The output is guaranteed AAA on launch — the `test_themes_toml.sh` unit test verifies this for every generated theme.
+
+## Wallpaper Discovery
+
+`rebuild-themes.sh` scans two tiers of wallpapers:
+
+### System Wallpapers
+
+- **macOS** — `/System/Library/Desktop Pictures/*.heic` and `/System/Library/Desktop Pictures/.thumbnails/*.heic`
+- **Linux** — `/usr/share/backgrounds/` and `/usr/share/wallpapers/` (recursive)
+
+### Custom Wallpapers
+
+- `~/Pictures/Wallpapers/*.{heic,jpg,png}` (or `$DOTFILES_WALLPAPER_DIR`)
+
+### Deduplication
+
+Custom wallpapers override system wallpapers on name collision. For Apple's dynamic HEIC files that contain multiple appearances in one file, the engine extracts each frame (`file.heic[0]`, `file.heic[1]`) and generates one theme per appearance.
+
+If a base wallpaper has explicit `-dark` and `-light` variants (e.g. `Big Sur Graphic.heic` + `Big Sur Graphic Dark.heic` + `Big Sur Graphic Light.heic`), the base is skipped to avoid duplicate theme names.
+
+## Dynamic HEIC (Apple Appearance Metadata)
+
+macOS dynamic wallpapers embed the `apple_desktop:apr` XMP metadata — a base64-encoded plist mapping image indices to appearance modes:
+
+```xml
+<rdf:Description rdf:about=""
+  xmlns:apple_desktop="http://ns.apple.com/namespace/1.0/"
+  apple_desktop:apr="YnBsaXN0MDDSAQIDBFFsUWQQABABCA0PERMAAAAAAAABAQAAAAAAAAAFAAAAAAAAAAAAAAAAAAAAFQ=="/>
+```
+
+Decoded:
+
+```xml
+<dict>
+    <key>l</key><integer>0</integer>  <!-- light = image 0 -->
+    <key>d</key><integer>1</integer>  <!-- dark = image 1 -->
+</dict>
+```
+
+`scripts/theme/merge-wallpaper.sh` combines separate dark+light files into a single dynamic HEIC with this metadata:
+
+```sh
+bash scripts/theme/merge-wallpaper.sh           # merge all pairs
+bash scripts/theme/merge-wallpaper.sh tahoe     # merge a specific family
+bash scripts/theme/merge-wallpaper.sh --dry-run # preview
+```
+
+macOS then auto-switches the displayed image based on the current Light/Dark mode — no application-level logic required.
+
+## Caching
+
+Per-wallpaper themes are cached in `~/.cache/dotfiles/themes/<name>.toml`. The cache is invalidated when the wallpaper's mtime is newer than the cached TOML. `dot theme rebuild --force` skips the cache.
+
+Full parallel rebuild of ~150 wallpapers takes ~3-5 minutes on modern hardware (4 parallel jobs, ~4 seconds per wallpaper). Incremental rebuilds (after adding 1-2 new wallpapers) take ~10 seconds.
+
+## Theme Application
+
+`dot-theme-sync` orchestrates the switch across every managed surface:
+
+| Surface | Mechanism |
+|:---|:---|
+| Ghostty | `chezmoi apply config.tmpl` + DBus reload or SIGUSR2 |
+| Alacritty | `chezmoi apply alacritty.toml.tmpl` |
+| Kitty | `chezmoi apply kitty.conf.tmpl` + SIGUSR1 |
+| WezTerm | `chezmoi apply wezterm.lua.tmpl` |
+| Tmux | `chezmoi apply tmux.conf.tmpl` + `source-file` |
+| Neovim | `chezmoi apply` + `--remote-expr` colorscheme switch over socket |
+| VS Code | `chezmoi apply settings.json.tmpl` |
+| GTK | `chezmoi apply gtk.css.tmpl` + `gsettings set gtk-theme` |
+| macOS accent | `defaults write -g AppleAccentColor` + `killall cfprefsd SystemUIServer Dock` |
+| Desktop wallpaper | `osascript` (macOS) or `gsettings picture-uri` (Linux) |
+
+See [Theming Reference](../03-reference/01-dot-cli.md#theme) for the exact command surface.
+
+## Bibliography
+
+- MacQueen, J. (1967). *Some methods for classification and analysis of multivariate observations.* Proceedings of the Fifth Berkeley Symposium on Mathematical Statistics and Probability.
+- Arthur, D. & Vassilvitskii, S. (2007). *K-Means++: The advantages of careful seeding.* ACM-SIAM Symposium on Discrete Algorithms.
+- CIE (1976). *Recommendations on uniform color spaces, color-difference equations, psychometric color terms.* Supplement No. 2 to CIE Publication No. 15.
+- W3C (2023). *Web Content Accessibility Guidelines (WCAG) 2.2.* <https://www.w3.org/TR/WCAG22/>
+
+## See Also
+
+- [Theming Guide](../../guides/THEMING.md) — quick-start and troubleshooting
+- [Theme Reference](../../reference/THEMES.md) — data schema and runtime behaviour
+- [Tutorial: Add a Wallpaper](../02-tutorials/02-add-wallpaper.md)

package/docs/manual/01-concepts/04-fleet.md

@@ -0,0 +1,142 @@
+# Fleet Architecture
+
+A "fleet" is two or more workstations sharing a single `.dotfiles` source repository. The fleet model handles per-host customization, drift detection, and cross-host trust propagation.
+
+## Single Source, Many Hosts
+
+All hosts clone the same repository. Platform and per-host differences are resolved at `chezmoi apply` time using three sources of data:
+
+1. **`.chezmoidata.toml`** — defaults for all hosts
+2. **`.chezmoidata/hardware.toml`** — machine presets (MacBook T2, Surface Pro, Geekom, etc.)
+3. **`~/.config/chezmoi/chezmoi.toml`** — per-host overrides, generated by `chezmoi init`
+
+The `machine` key in `chezmoi.toml` selects which preset applies:
+
+```toml
+# ~/.config/chezmoi/chezmoi.toml on a MacBook
+[data]
+machine = "macbook-t2"
+theme = "tahoe-dark"
+```
+
+Templates read `.chezmoi.hardware` to get the resolved preset:
+
+```go
+{{- $hw := index .hardware .machine }}
+display_scale = {{ $hw.display_scale }}  // 2.0 for MacBook, 1.5 for Surface
+```
+
+## Hardware Presets
+
+`.chezmoidata/hardware.toml` ships with ~12 presets covering common laptop/desktop/NUC configurations. Each preset defines:
+
+| Field | Purpose |
+|:---|:---|
+| `display_scale` | 1.0, 1.25, 1.5, 1.75, 2.0 |
+| `kbd_layout` | colemak-dh, qwerty, dvorak |
+| `modifier_mode` | left-cmd-control, fn-swap, standard |
+| `perf_profile` | laptop, desktop, low-power |
+| `wm` | aerospace, niri, gnome, kde |
+| `features.X` | per-preset feature toggles |
+
+Add a new preset by appending to `hardware.toml` — no code changes needed.
+
+## Drift Detection
+
+`dot drift` compares the current machine state against the rendered template output and reports:
+
+| Drift Type | Example |
+|:---|:---|
+| **Added** | File exists locally but not in source |
+| **Removed** | Source deletes a file still present locally |
+| **Modified** | Local edit to a managed file |
+| **Permission** | Chmod/chown changes |
+| **Symlink target** | Link retargeted |
+
+Drift is normal during development. `dot heal` reconciles the source → local direction. `dot apply` overwrites drift; `dot diff` previews the change without applying.
+
+## Fleet Attestation
+
+`dot fleet attest` runs `dot attest` locally and collects signed attestations from every known host (via SSH). The combined report shows:
+
+- Whether all hosts are on the same Git SHA
+- Whether policy hashes match
+- Which hosts have drift
+- Which hosts have verified signatures
+
+A typical output:
+
+```
+Fleet Attestation — v0.2.500
+
+Host           Git SHA    Policy    Tools OK   Drift   Verified
+-------------- ---------- --------- ---------- ------- --------
+macbook-t2     abc123d    0x7f2a…   ✓          0       ✓
+surface-pro    abc123d    0x7f2a…   ✓          2       ✓
+geekom-a9      def456e    0x7f2a…   ✗ (chezmoi 2.45)   ✗
+-------------- ---------- --------- ---------- ------- --------
+FLEET STATUS: 2/3 aligned; drift on geekom-a9
+```
+
+This becomes an auditable artifact — useful for compliance reporting, incident response, and post-upgrade validation.
+
+## Fleet Deployment Workflow
+
+Recommended rollout procedure for fleet-wide changes:
+
+1. **Develop on one host** — make the change, test locally with `dot apply --dry-run` then `dot apply`
+2. **Open a PR** — CI validates shellcheck, tests, security scanners
+3. **Merge to master** — signed commit required
+4. **Per-host pull** — on each fleet host: `dot update` (git pull + apply)
+5. **Verify alignment** — run `dot fleet attest` from any host
+
+For urgent rollback: every host can independently run `dot rollback` to return to the previous known-good state (stored in `~/.local/state/dotfiles/snapshots/`).
+
+## Cross-Host Trust
+
+Each host has its own SSH ED25519 signing key. To establish mutual trust:
+
+1. On each host: `cat ~/.ssh/id_ed25519.pub` — capture the public key
+2. Add every host's public key to `~/.ssh/allowed_signers` on every other host
+3. Commit `allowed_signers` to the source repository (it's public-key material, safe to share)
+4. After `dot apply`, any host can verify commits and attestations from any other host
+
+This creates a **web-of-trust** among your own fleet. No central CA, no external service — just SSH keys.
+
+## Machine-Scoped Secrets
+
+Some secrets must decrypt only on specific hosts (e.g. a work VPN config that doesn't belong on a personal laptop). The SOPS approach:
+
+```yaml
+# dot_config/vpn.sops.yaml
+vpn_key: ENC[AES256_GCM,data:...]
+sops:
+  age:
+    - recipient: age1... # work laptop only
+      enc: |
+        -----BEGIN AGE ENCRYPTED FILE-----
+        ...
+```
+
+Only the host with the matching Age private key can decrypt. Other hosts see the encrypted file but cannot read the content.
+
+## Fleet Operational Commands
+
+| Command | Purpose |
+|:---|:---|
+| `dot fleet` | Show all known hosts and their last-seen status |
+| `dot fleet attest` | Collect signed attestations from every host |
+| `dot fleet diff` | Compare rendered config across hosts |
+| `dot fleet sync` | Run `dot update` on every host (requires SSH access) |
+
+## Limitations
+
+- Fleet commands assume SSH connectivity between hosts (or a dedicated orchestration agent — see [Roadmap](../../operations/ROADMAP.md))
+- Secret rotation requires re-encrypting for all recipients; automated with `dot secrets rotate`
+- There is no central policy store — policy is versioned in the Git repository itself
+
+## See Also
+
+- [Fleet Deployment Architecture](../../architecture/fleet-deployment.md) — diagrams
+- [Trust Model](02-trust-model.md)
+- [Tutorial: Deploy to a Fleet](../02-tutorials/05-deploy-fleet.md)

package/docs/manual/01-concepts/05-self-healing.md

@@ -0,0 +1,197 @@
+# Self-Healing
+
+`.dotfiles` detects, diagnoses, and repairs configuration drift, missing tools, broken symlinks, and environmental damage — often without user intervention.
+
+## The Self-Healing Loop
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│  dot doctor │ ──► │   detect    │ ──► │   report    │
+└─────────────┘     └─────────────┘     └─────────────┘
+                           │
+                           ▼
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│  dot heal   │ ──► │   repair    │ ──► │   verify    │
+└─────────────┘     └─────────────┘     └─────────────┘
+                           │
+                           ▼ (on failure)
+┌─────────────┐     ┌─────────────┐
+│dot rollback │ ──► │   revert    │
+└─────────────┘     └─────────────┘
+```
+
+## `dot doctor` — Detection
+
+`dot doctor` runs ~40 health checks grouped into categories:
+
+| Category | Checks |
+|:---|:---|
+| **Paths** | `~/.local/bin`, `~/.cargo/bin`, Mise shim order, Homebrew prefix |
+| **Tools** | Required: git, chezmoi. Optional: mise, nix, age, sops, pandoc |
+| **Chezmoi** | Source dir exists, data file valid, no uncommitted drift |
+| **Shell** | Default shell matches profile, startup time <500ms |
+| **Security** | SSH keys present, Age key present, gitleaks baseline |
+| **Portability** | Git user.email set, LC_ALL sane, TERM recognized |
+
+Exit codes:
+
+| Code | Meaning |
+|:---|:---|
+| 0 | All checks passed |
+| 1 | Warnings (non-blocking) |
+| 2 | Critical failures (tool missing, config broken) |
+
+Flags:
+
+- `--score` / `-s` — numeric health score (0-100)
+- `--heal` / `-H` — auto-fix detected issues (equivalent to `dot doctor && dot heal`)
+- `--json` / `-j` — machine-readable output for CI/monitoring
+- `--verbose` / `-v` — show every check (default shows only failures)
+
+## `dot heal` — Repair
+
+`dot heal` addresses three common failure modes:
+
+### 1. Missing Tools
+
+Reinstalls tools listed in `.chezmoidata.toml` that aren't on PATH:
+
+```sh
+dot heal
+# [heal] jq not found, installing via mise
+# [heal] age not found, installing via homebrew
+# [heal] ✓ 2 tools installed
+```
+
+Priority order: mise → homebrew (macOS) → apt/dnf (Linux) → nix → manual install script.
+
+### 2. Chezmoi Drift
+
+Runs `chezmoi apply --force` to reconcile local files back to the source state. Skipped files (excluded via `.chezmoiignore`) are left alone.
+
+### 3. Broken Symlinks & Missing Files
+
+Detects dangling symlinks (target doesn't exist) and re-applies chezmoi to recreate them. Missing critical files (e.g. `~/.zshrc`) trigger a targeted re-render.
+
+### Flags
+
+- `--dry-run` / `-n` — show what would be fixed, don't change anything
+- `--force` / `-f` — skip confirmation prompts
+- `--tool <name>` — heal only a specific tool
+
+### Exit Codes
+
+- 0 — nothing to heal or all fixes succeeded
+- 1 — some repairs failed, manual intervention required
+
+## `dot chaos` — Self-Test
+
+`dot chaos` intentionally corrupts the local installation to verify `dot heal` can recover it. This is **destructive** — run only in ephemeral environments (containers, VMs, fresh installs).
+
+Corruption scenarios:
+
+| Scenario | What it breaks |
+|:---|:---|
+| `symlink` | Delete 3 random managed symlinks |
+| `config` | Rewrite `~/.gitconfig` with garbage |
+| `tool` | `mv` a critical binary out of PATH |
+| `permission` | `chmod 000` on a dotfile |
+| `all` | Run all scenarios sequentially |
+
+Typical workflow:
+
+```sh
+docker run --rm -it ubuntu bash
+# inside container:
+bash -c "$(curl -fsSL https://.../install.sh)"
+dot doctor    # baseline
+dot chaos all # break things
+dot heal      # fix
+dot doctor    # verify
+```
+
+This is part of CI: every PR runs `dot chaos` in a Docker container and validates `dot heal` restores a healthy state.
+
+## `dot rollback` — Revert
+
+Before every `dot apply`, chezmoi writes a snapshot to `~/.local/state/dotfiles/snapshots/YYYY-MM-DD-HHMMSS/`. `dot rollback` restores the most recent snapshot:
+
+```sh
+dot rollback              # revert to the most recent snapshot
+dot rollback status       # list available snapshots
+dot rollback restore 3    # restore snapshot #3
+dot rollback clean        # delete snapshots older than 30 days
+```
+
+Snapshots include:
+- Every file chezmoi would have overwritten
+- The previous `.chezmoidata.toml` and `chezmoi.toml`
+- A pointer to the Git SHA at apply time
+
+They do **not** include:
+- Generated caches (`~/.cache/`)
+- Tool binaries (Mise-managed)
+- External state (databases, remote repos)
+
+## `dot bundle` — Offline Recovery
+
+`dot bundle` creates a self-contained archive that can restore the workstation without network access:
+
+```
+dotfiles-bundle-v0.2.500-20260416.tar.zst
+├── source/              # Full git clone at current HEAD
+├── tools/               # Pre-built chezmoi binary + mise
+├── secrets/             # Age-encrypted snapshot of ~/.config/age/
+├── manual/              # Offline manual (HTML + PDF)
+├── attestation.json     # Signed state
+├── install-offline.sh   # Bootstrap script
+└── SHA256SUMS           # Integrity checksums
+```
+
+Usage:
+
+```sh
+dot bundle                        # create bundle in ~/Downloads/
+dot bundle --to /path/to/usb.img  # write to external storage
+dot bundle restore bundle.tar.zst # restore from bundle
+```
+
+Recovery use case: you're stranded on a new machine with no internet. Copy the bundle over (USB, phone tether, Bluetooth). Run `bash install-offline.sh`. You have a working dotfiles environment in <60 seconds, no network required.
+
+## Observability
+
+### Health Score
+
+`dot score` returns a 0-100 score combining:
+
+| Dimension | Weight |
+|:---|---:|
+| Tool availability | 30 |
+| Chezmoi drift | 20 |
+| Security gates (sigs, secrets, Age key) | 20 |
+| Performance (shell startup, cache health) | 15 |
+| Compliance (policy hash match) | 15 |
+
+Scores:
+- 90-100 — healthy
+- 70-89 — minor issues
+- 50-69 — needs attention
+- <50 — run `dot heal` immediately
+
+### Metrics
+
+`dot metrics` shows recent observations: shell startup time, last-apply duration, heal events, chaos self-tests, CVE counts from SBOM scan. Metrics are stored locally in `~/.local/state/dotfiles/metrics.jsonl` (append-only, one line per event).
+
+## Design Principles
+
+1. **Idempotent** — running `dot apply` or `dot heal` twice has the same effect as once
+2. **Reversible** — every mutation creates a rollback point
+3. **Observable** — failures produce actionable error messages with exit codes
+4. **Offline-capable** — core flows (detect, heal, rollback) work without network
+5. **Minimally invasive** — repairs are scoped to the smallest unit that fixes the problem
+
+## See Also
+
+- [Reliability Operations](../../operations/RELIABILITY.md)
+- [Tutorial: First Install](../02-tutorials/01-first-install.md)
+- [Cookbook: Troubleshooting](../04-cookbook/02-troubleshooting.md)