@sebastienrousseau/dotfiles 0.2.499 → 0.2.500

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)

package/docs/manual/02-tutorials/01-first-install.md

@@ -0,0 +1,192 @@
+# Tutorial: First Install
+
+End-to-end installation and verification, from zero to a fully-working environment in under 5 minutes.
+
+## Prerequisites
+
+- macOS 14+, Ubuntu/Debian 20.04+, Arch (rolling), Fedora 39+, or WSL2 on Windows 11
+- `git` and `curl` installed
+- Shell access (Zsh, Fish, or Bash)
+- Optional but recommended: SSH key for signing commits
+
+## Step 1: Run the Installer
+
+```sh
+bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh)"
+```
+
+The installer:
+1. Verifies prerequisites (`git`, `curl`, write access to `~`)
+2. Downloads chezmoi via the SHA256-verified installer
+3. Clones the dotfiles source to `~/.dotfiles`
+4. Runs `chezmoi init` to prompt for per-machine settings
+5. Runs `chezmoi apply` with progress output
+
+Expected output:
+
+```
+[install] Verifying prerequisites
+[install] Installing chezmoi (verified SHA256)
+[install] Cloning source to ~/.dotfiles
+[install] Running chezmoi init (interactive)
+  Git email: you@example.com
+  Machine preset [macbook-t2]:
+  Default theme [tahoe-dark]:
+  Default shell [fish]:
+[install] Applying configuration (180 files)
+[install] ✓ Installation complete
+```
+
+## Step 2: Verify
+
+Open a new shell and run:
+
+```sh
+dot doctor
+```
+
+Expected output:
+
+```
+◈ DOTFILES
+Dot • Diagnostics
+
+--- Health Check ---
+  ✓ Paths             ~/.local/bin, mise shims present
+  ✓ Tools             git, chezmoi, mise installed
+  ✓ Chezmoi           clean (no drift)
+  ✓ Shell             fish (500ms startup)
+  ✓ Security          SSH key present, Age key present
+  ✓ Portability       LC_ALL=en_US.UTF-8, TERM=xterm-256color
+
+Score: 98/100
+```
+
+Any warnings will be accompanied by a suggested fix.
+
+## Step 3: Take the Tour
+
+```sh
+dot learn
+```
+
+An interactive walkthrough covering:
+
+- Shell basics and aliases
+- Secrets workflow
+- Theme switching
+- Performance tuning
+- Security hardening
+
+Each section takes 30-60 seconds. You can skip sections or exit at any time.
+
+## Step 4: Customize
+
+### Per-Machine Settings
+
+Edit `~/.config/chezmoi/chezmoi.toml`:
+
+```toml
+[data]
+machine = "macbook-t2"       # see .chezmoidata/hardware.toml for presets
+theme = "tahoe-dark"         # see `dot theme list`
+default_shell = "fish"       # fish, zsh, bash
+terminal_font_family = "JetBrainsMono Nerd Font"
+terminal_font_size = 12
+```
+
+### Feature Flags
+
+Edit `.chezmoidata.toml` in the source directory (`~/.dotfiles/.chezmoidata.toml`):
+
+```toml
+[features]
+dms = false                  # Dank Material Shell (Niri)
+linux_desktop = false        # Linux-specific desktop configs
+waybar = false               # Waybar status bar
+```
+
+After editing, apply:
+
+```sh
+dot apply
+```
+
+## Step 5: Add Your Identity
+
+If you have an SSH key, configure signed commits:
+
+```sh
+git config --global user.signingkey ~/.ssh/id_ed25519.pub
+git config --global commit.gpgsign true
+git config --global gpg.format ssh
+git config --global gpg.ssh.allowedSignersFile ~/.ssh/allowed_signers
+```
+
+Add your own key to `~/.ssh/allowed_signers`:
+
+```
+you@example.com ssh-ed25519 AAAA...
+```
+
+Test:
+
+```sh
+cd ~/.dotfiles
+git commit --allow-empty -m "test: signature"
+git verify-commit HEAD
+# Good "git" signature for you@example.com
+```
+
+## Step 6: First Theme Switch
+
+```sh
+dot theme
+```
+
+A picker opens showing all paired wallpaper themes on your system. Select one and press Enter. The terminal, editor, desktop wallpaper, and macOS accent color update in about 3 seconds.
+
+## Troubleshooting
+
+If `dot doctor` shows failures:
+
+```sh
+dot heal      # auto-fix common issues
+dot heal -n   # dry-run first to see what would change
+```
+
+If the installation is broken beyond repair:
+
+```sh
+dot rollback  # restore the previous known-good state
+```
+
+If `dot doctor` still fails after heal + rollback, check:
+
+- `~/.local/state/dotfiles/install.log` — installer log
+- `~/.local/state/dotfiles/heal.log` — heal attempts
+- `chezmoi doctor` — chezmoi-specific diagnostics
+
+Still stuck? See [Cookbook: Troubleshooting](../04-cookbook/02-troubleshooting.md).
+
+## What Got Installed
+
+After `dot doctor` reports a healthy score, you have:
+
+| Surface | What's There |
+|:---|:---|
+| **Shell** | Fish (default), Zsh, Nushell, Bash all configured with cached init |
+| **Editor** | Neovim with lazy.nvim + LSP + theme-synced colorscheme |
+| **Terminal** | Ghostty/Alacritty/Kitty/WezTerm configs (pick whichever is installed) |
+| **Git** | Signed commits, delta diff, conventional commit template |
+| **AI tooling** | Claude Code, Codex, Copilot CLI, Gemini CLI via mise |
+| **Secret store** | Age key, SOPS config, `dot secrets` command ready |
+| **Security** | Gitleaks, detect-secrets baseline, signed attestation log |
+| **Theme engine** | K-Means wallpaper extractor, system + custom wallpaper discovery |
+
+## Next
+
+- [Tutorial: Add a Wallpaper → Theme](02-add-wallpaper.md)
+- [Tutorial: Create a Machine Profile](03-create-profile.md)
+- [Tutorial: Encrypt a Secret](04-encrypt-secret.md)
+- [Cookbook: 30+ recipes](../04-cookbook/01-recipes.md)