@sebastienrousseau/dotfiles 0.2.520 → 0.2.521

package/docs/manual/04-cookbook/02-troubleshooting.md

@@ -1,351 +0,0 @@
----
-render_with_liquid: false
----
-{% raw %}
-
-# Cookbook: Troubleshooting
-
-Symptom → cause → fix.
-
-## Installation
-
-### Symptom: `install.sh` fails with "chezmoi not found"
-
-**Cause**: `/usr/local/bin` or `~/.local/bin` not in PATH at install time.
-
-**Fix**:
-
-```sh
-export PATH="$HOME/.local/bin:$PATH"
-bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh)"
-```
-
-### Symptom: "could not create directory ~/.local/share/chezmoi"
-
-**Cause**: Permission issue on `~/.local`.
-
-**Fix**:
-
-```sh
-mkdir -p ~/.local/share ~/.local/state ~/.local/bin
-chmod 755 ~/.local ~/.local/share
-```
-
-### Symptom: Install hangs at "Downloading chezmoi"
-
-**Cause**: Slow network or corporate proxy.
-
-**Fix**:
-
-```sh
-export https_proxy=$HTTP_PROXY  # if applicable
-# Or pre-download chezmoi manually
-brew install chezmoi            # macOS
-apt install chezmoi             # Debian 13+
-```
-
-## Apply / Sync
-
-### Symptom: `dot apply` reports "file modified, skipping"
-
-**Cause**: Chezmoi detected local drift on a managed file.
-
-**Fix**:
-
-```sh
-dot diff                    # see what differs
-dot apply --force           # overwrite local
-# OR
-dot add <path>              # import local change to source
-```
-
-### Symptom: "template: error calling index"
-
-**Cause**: A template references a missing data field.
-
-**Fix**: Check that your `.chezmoidata.toml` has the required field. For example:
-
-```sh
-chezmoi execute-template '{{- $hw := index .hardware .machine -}}{{ $hw.wm }}'
-```
-
-If `machine` is not set in your `~/.config/chezmoi/chezmoi.toml`, `index` returns nil. Set:
-
-```toml
-[data]
-machine = "macbook-t2"
-```
-
-### Symptom: Apply succeeds but shell doesn't reflect changes
-
-**Cause**: Cached init scripts are stale.
-
-**Fix**:
-
-```sh
-dot clean-cache
-dot prewarm
-exec $SHELL -l
-```
-
-## Theme
-
-### Symptom: `dot theme` shows no themes
-
-**Cause**: No wallpapers discovered, themes.toml not generated.
-
-**Fix**:
-
-```sh
-dot theme rebuild --force
-```
-
-### Symptom: `dot theme <name>` errors "unknown theme"
-
-**Cause**: Theme name doesn't exist in `themes.toml`.
-
-**Fix**:
-
-```sh
-dot theme list            # see valid names
-dot theme rebuild --force # regenerate if expected but missing
-```
-
-### Symptom: macOS accent color doesn't update
-
-**Cause**: System Settings UI cached the old value.
-
-**Fix**: `dot-theme-sync` now calls `killall cfprefsd SystemUIServer Dock "System Settings"`. If it still doesn't refresh:
-
-```sh
-killall -KILL Dock SystemUIServer
-sudo killall -KILL cfprefsd
-```
-
-Or log out and back in.
-
-### Symptom: Wallpaper not applying
-
-**Cause**: Wrong format or missing DE support on Linux.
-
-**Fix**:
-
-```sh
-# Check the wallpaper file exists
-ls -la ~/Pictures/Wallpapers/
-
-# On Linux, verify HEIC → PNG conversion tool
-command -v magick || command -v heif-convert || command -v convert
-# Install if needed:
-sudo apt install imagemagick-7
-```
-
-### Symptom: Theme applies but Ghostty doesn't reload
-
-**Cause**: Ghostty DBus or SIGUSR2 signaling failed.
-
-**Fix**:
-
-```sh
-# Restart Ghostty manually, or:
-pkill -USR2 ghostty 2>/dev/null
-# Or quit+relaunch the app
-```
-
-## Secrets
-
-### Symptom: "could not decrypt: no age key"
-
-**Cause**: `~/.config/age/keys.txt` missing or unreadable.
-
-**Fix**:
-
-```sh
-ls -la ~/.config/age/keys.txt
-# Should be: -rw------- 1 user user
-chmod 600 ~/.config/age/keys.txt
-
-# If missing, restore from password manager or regenerate (requires re-encrypting all secrets)
-```
-
-### Symptom: SOPS says "wrong recipient"
-
-**Cause**: Your Age public key isn't listed in the file's recipients.
-
-**Fix**:
-
-```sh
-# Add your public key to .sops.yaml
-sops updatekeys path/to/file.sops.yaml
-
-# Or, ask a recipient to re-encrypt for you
-```
-
-### Symptom: Plaintext leak detected by gitleaks
-
-**Cause**: A secret was committed to Git history.
-
-**Fix**:
-
-```sh
-# Immediate mitigation
-dot verify --security   # confirm which file
-git rm --cached <file>
-echo "<file>" >> .gitignore
-git commit -sS -m "fix(security): remove leaked file"
-
-# Rotate the leaked secret upstream (it's now public)
-# Rewrite Git history if needed (requires force-push):
-git filter-repo --path <file> --invert-paths
-```
-
-## Performance
-
-### Symptom: Shell startup >500ms
-
-**Cause**: Heavy modules loaded synchronously.
-
-**Fix**:
-
-```sh
-dot benchmark --detailed
-# Identify which module is slow
-
-# Rebuild caches
-dot prewarm
-
-# Disable heavy modules temporarily
-# Edit ~/.config/zsh/.zshrc.local (or equivalent) to skip them
-```
-
-### Symptom: `dot doctor` score <70
-
-**Cause**: Multiple health issues.
-
-**Fix**:
-
-```sh
-dot doctor --verbose    # see every failure
-dot heal                # auto-fix what's possible
-dot doctor              # recheck
-```
-
-### Symptom: Mise tools not found
-
-**Cause**: Mise shim not activated.
-
-**Fix**:
-
-```sh
-eval "$(mise activate zsh)"  # or fish, bash
-dot doctor                    # confirm
-```
-
-## Build Artifacts
-
-### Symptom: Cargo builds to `target/` instead of `/tmp/builds/cargo`
-
-**Cause**: `~/.cargo/config.toml` not managed or was overridden.
-
-**Fix**:
-
-```sh
-chezmoi apply ~/.cargo/config.toml
-cat ~/.cargo/config.toml | grep target-dir
-# Should be: target-dir = "/tmp/builds/cargo"
-```
-
-### Symptom: `/tmp/builds/` doesn't exist
-
-**Cause**: Created by shell init, but shell wasn't restarted.
-
-**Fix**:
-
-```sh
-mkdir -p /tmp/builds
-# Or restart shell
-exec $SHELL -l
-```
-
-## Fleet
-
-### Symptom: `dot fleet attest` hangs
-
-**Cause**: A fleet host is unreachable.
-
-**Fix**:
-
-```sh
-# Check connectivity to each host
-for host in macbook-t2 surface-pro geekom-a9; do
-  ssh -o ConnectTimeout=5 $host 'echo OK' || echo "FAIL: $host"
-done
-
-# Remove unreachable hosts from ~/.config/dotfiles/fleet.toml temporarily
-```
-
-### Symptom: Attestation signature fails
-
-**Cause**: Remote host's SSH public key not in local `~/.ssh/allowed_signers`.
-
-**Fix**:
-
-```sh
-# On the remote host:
-ssh remote-host 'cat ~/.ssh/id_ed25519.pub'
-# Copy the output and append to your ~/.ssh/allowed_signers
-```
-
-## CI
-
-### Symptom: PR fails on "Shell Lint (Zero Warnings)"
-
-**Cause**: `shfmt` formatting differs from canonical.
-
-**Fix**:
-
-```sh
-shfmt -w -i 2 -ci scripts/**/*.sh install.sh .chezmoitemplates/**/*.sh
-# Commit the changes
-```
-
-### Symptom: PR fails on "100% Coverage"
-
-**Cause**: New code added without tests.
-
-**Fix**:
-
-```sh
-bash examples/example-coverage-gate.sh
-# Identifies uncovered modules
-
-# Add a test in tests/unit/<domain>/test_<module>.sh
-```
-
-### Symptom: Checkov SARIF upload times out
-
-**Cause**: Known infrastructure flake (Azure runner slow apt mirrors).
-
-**Fix**: The workflow already guards this with `hashFiles('reports/checkov.sarif')`. If you see this after the guard was added, check the Checkov step output for errors.
-
-## Getting More Help
-
-1. Check [FAQ](03-faq.md)
-2. Read the relevant [concept chapter](../01-concepts/)
-3. Open an issue: <https://github.com/sebastienrousseau/dotfiles/issues>
-
-When filing an issue, include:
-
-```sh
-dot doctor --json
-dot version
-uname -a
-chezmoi --version
-```
-
-## See Also
-
-- [Self-Healing concept](../01-concepts/05-self-healing.md)
-- [FAQ](03-faq.md)
-- [Security: Incident Response](../../security/INCIDENT_RESPONSE.md)
-{% endraw %}

package/docs/manual/04-cookbook/03-faq.md

@@ -1,175 +0,0 @@
----
-render_with_liquid: false
----
-
-# Cookbook: Frequently Asked Questions
-
-## General
-
-### Why use this over stow, yadm, or a plain Git repo?
-
-Because it's not just a dotfiles manager. It's a workstation baseline with:
-
-- Cryptographic attestation
-- AI/MCP policy enforcement
-- Wallpaper-driven theme engine (WCAG AAA)
-- Self-healing + chaos testing
-- Fleet management
-- Per-platform rendering via chezmoi templates
-
-If you only need to symlink `.bashrc`, use stow. If you're operating a fleet of signed, attested, AI-aware workstations, use this.
-
-### Does it work on Windows?
-
-Only via WSL2. Native Windows PowerShell support exists for baseline parity (aliases, prompt), but the full feature set (chezmoi, Mise, theme engine) requires WSL2.
-
-### Is it production-ready?
-
-Yes — it's the author's daily driver across multiple hosts and receives regular releases (see `CHANGELOG.md`). CI enforces 100% executable-module mapping and a ratcheted measured Bash line-coverage floor, plus zero-warning linting, WCAG AAA for themes, SBOM + CVE scanning, and signed-commit verification. The current measured coverage and exclusions are documented in `docs/operations/COVERAGE.md`.
-
-### Can I fork it and use it without attribution?
-
-Yes — MIT License. Attribution is appreciated but not required.
-
-## Themes
-
-### Why K-Means in CIELAB instead of RGB?
-
-CIELAB distances approximate human perception. A Δ in RGB might look identical to your eye in one part of the color space and very different in another. Clustering in Lab produces palettes where "close" colors actually look close. See [Theme Engine](../01-concepts/03-theme-engine.md).
-
-### Why not pre-built themes like Catppuccin or Rosé Pine?
-
-Two reasons:
-
-1. **Maintenance** — 100+ themes × 20+ applications = thousands of template variables to keep in sync. Generation from wallpapers eliminates that.
-2. **User agency** — users bring their own wallpapers. The theme adapts to them, not the other way around.
-
-The engine can still produce Catppuccin-like output: give it a Catppuccin wallpaper and you get Catppuccin-aligned terminal colors.
-
-### Does it ship wallpapers?
-
-No. Apple/Microsoft/distro-vendor wallpapers are copyrighted. The repo discovers wallpapers that are already on the user's system (at `~/Pictures/Wallpapers/` or the OS's system wallpaper directory). Users bring their own images.
-
-### How do I control the accent color?
-
-You don't directly — the accent hue is extracted from the wallpaper. But `_compute_accent()` picks the most chromatic cluster, then darkens it until white text meets 7:1 contrast. If you want a specific accent, choose a wallpaper with that hue dominant.
-
-### Can I use my own theme without a wallpaper?
-
-Not directly — the engine expects a source image. You could:
-
-1. Pick a wallpaper whose palette you want
-2. Let the engine generate the theme
-3. Lock the generated `.toml` entry by copying to a non-regenerated path
-
-But this defeats the point. If you have a specific palette in mind, generate a solid-color or gradient image with those colors and use that.
-
-## Secrets
-
-### Why Age instead of GPG?
-
-GPG is notoriously complex. Age is simpler, uses modern crypto (X25519 + ChaCha20-Poly1305), and has no legacy baggage. It's the tool [SOPS recommends](https://github.com/getsops/sops#encrypting-using-age).
-
-### Why commit encrypted secrets at all?
-
-- **Traceable** — Git history shows when secrets changed
-- **Auditable** — ciphertext is testable without decryption
-- **Portable** — clone the repo anywhere, decrypt with your key
-- **No external dependency** — no Vault/AWS Secrets Manager/etc.
-
-The alternative (storing secrets outside the repo) creates sync headaches across fleet hosts. Encrypted-at-rest-in-repo is simpler and just as secure if keys are managed correctly.
-
-### What if I lose my Age private key?
-
-You lose access to all secrets encrypted only for that key. Recovery requires another recipient (another host with a valid key) to decrypt and re-encrypt. Fleet setups use multiple recipients for this reason — see [Deploy to Fleet](../02-tutorials/05-deploy-fleet.md).
-
-## AI & Agents
-
-### Does this require an API key?
-
-No. The AI tools (Claude Code, Codex, Copilot) are installed but require their own authentication. `dot ai` shows what's present without invoking any remote service.
-
-### What is MCP?
-
-The [Model Context Protocol](https://modelcontextprotocol.io/) is a standard for connecting AI models to tools and data sources. `.dotfiles` includes policy enforcement for MCP-aware agents: allowlists, attestation, and signed registries. See [Trust Model](../01-concepts/02-trust-model.md).
-
-### Can I add my own agent profile?
-
-Yes. Drop a Markdown file in `dot_config/ai/patterns/`. Each file describes a profile (architect, hardener, etc.). `dot mode <name>` switches between them.
-
-## Fleet
-
-### How many hosts can I manage?
-
-No hard limit. The `dot fleet` commands SSH sequentially by default, so large fleets (>20 hosts) benefit from parallel invocation. For industrial scale, pair with Ansible/Nix/Puppet; `.dotfiles` handles the user-level config, not system administration.
-
-### Do I need a central server?
-
-No. Everything is Git-based. No central orchestration service, no daemon. Each host pulls independently.
-
-### Can two hosts have different themes?
-
-Yes. Each host's `~/.config/chezmoi/chezmoi.toml` can set its own `theme`. This is per-host override — not shared in the repo.
-
-## Performance
-
-### Why is my shell startup 800ms when the budget is 500ms?
-
-Check what's loaded:
-
-```sh
-DOTFILES_DEBUG=1 zsh -i -c exit 2>&1 | grep -E '\[debug [0-9]+ms\]'
-```
-
-Common culprits:
-
-- nvm loading Node on every shell (use lazy loading)
-- `mise activate` with aggressive hook-env (set `activate_aggressive = false`)
-- Plugin manager scanning for updates
-
-Run `dot benchmark --detailed` to attribute cost.
-
-### Can I disable prewarming?
-
-Yes — but your cold shell startup will be slow. Remove the prewarm invocation from your shell profile or skip `dot prewarm` after apply.
-
-## Troubleshooting Community
-
-### Where do I report bugs?
-
-GitHub issues: <https://github.com/sebastienrousseau/dotfiles/issues>. Include output of `dot doctor --json` and your platform.
-
-### Where do I ask usage questions?
-
-GitHub discussions, or mention in the issue you open. The maintainer responds best to issues with clear repro steps.
-
-### Is there a Discord / Slack?
-
-Not currently.
-
-## Philosophy
-
-### Why so much emphasis on attestation?
-
-Because AI agents operating on your workstation can do anything you can. Attestation is the audit trail — who ran what, when, with which policy. Without it, agent operations are black boxes.
-
-### Why MIT License?
-
-To maximize adoption and contribution. MIT is compatible with commercial use; copyleft alternatives would restrict who can use the code.
-
-### Why no GUI configurator?
-
-Text + Git is the optimal interface for a workstation baseline:
-
-- Versioned (Git history)
-- Reproducible (same input → same output)
-- Auditable (diff-able)
-- Scriptable (any `dot` command can be invoked programmatically)
-
-A GUI adds complexity without benefit over editing `.chezmoidata.toml` directly.
-
-## See Also
-
-- [Troubleshooting](02-troubleshooting.md)
-- [Recipes](01-recipes.md)
-- [GitHub Discussions](https://github.com/sebastienrousseau/dotfiles/discussions)

package/docs/manual/05-appendices/A-platform-matrix.md

@@ -1,101 +0,0 @@
----
-render_with_liquid: false
----
-
-# Appendix A: Platform Support Matrix
-
-## Supported Platforms
-
-| OS | Version | Support | Notes |
-|:---|:---|:---:|:---|
-| macOS | 14 (Sonoma) | ✓ full | Primary development platform |
-| macOS | 15 (Sequoia) | ✓ full | |
-| macOS | 26 (Tahoe) | ✓ full | |
-| Ubuntu | 22.04 LTS | ✓ full | |
-| Ubuntu | 24.04 LTS | ✓ full | CI reference platform |
-| Debian | 12 (Bookworm) | ✓ full | |
-| Debian | 13 (Trixie) | ✓ full | |
-| Arch Linux | rolling | ✓ full | |
-| CachyOS | rolling | ✓ full | Arch-based |
-| Fedora | 39 | ✓ | Less tested |
-| Fedora | 40, 41 | ✓ | Less tested |
-| openSUSE | Tumbleweed | ✓ | Less tested |
-| Alpine | 3.20 | ⚠ partial | POSIX shells only; no Fish |
-| WSL2 | Ubuntu 22.04+ | ✓ full | Windows 11 host |
-| WSL2 | Debian | ✓ full | |
-| Windows PowerShell | 7.5+ | ⚠ baseline | Aliases + prompt; no chezmoi |
-| FreeBSD | 14 | ✗ untested | |
-| Termux (Android) | latest | ✗ untested | |
-
-## Supported Shells
-
-| Shell | Version | Support |
-|:---|:---|:---:|
-| Fish | 3.6+ | ✓ primary |
-| Zsh | 5.9+ | ✓ full |
-| Bash | 5.0+ | ✓ full |
-| Nushell | 0.90+ | ✓ full |
-| PowerShell | 7.5+ | ⚠ baseline |
-
-## Supported Architectures
-
-| Arch | Status |
-|:---:|:---:|
-| amd64 / x86_64 | ✓ |
-| arm64 / aarch64 | ✓ |
-| armv7 | ⚠ best-effort |
-| riscv64 | ✗ untested |
-
-## Required Binaries
-
-| Binary | Purpose | Install |
-|:---|:---|:---|
-| `git` | Version control | System package manager |
-| `curl` | Installer | System package manager |
-| `chezmoi` | Template engine | Installer downloads verified binary |
-
-## Optional Binaries (installed by Mise on first apply)
-
-| Binary | Purpose |
-|:---|:---|
-| `mise` | Runtime version manager |
-| `age` | Secret encryption |
-| `sops` | YAML secret encryption |
-| `pandoc` | Manual generation |
-| `shellcheck` | Shell linting |
-| `shfmt` | Shell formatting |
-| `starship` | Prompt |
-| `fzf` | Fuzzy finder |
-| `zoxide` | Smart `cd` |
-| `atuin` | Shell history sync |
-| `delta` | Git diff pager |
-| `lazygit` | TUI Git client |
-| `neovim` | Editor |
-
-## Tested CI Environments
-
-| Environment | Workflow |
-|:---|:---|
-| macOS 14 (GHA) | `ci.yml`, `ci-enforced.yml` |
-| Ubuntu 24.04 (GHA) | `ci.yml`, `ci-enforced.yml` |
-| GitHub Codespaces | `devcontainer-prebuild.yml` |
-| Docker Ubuntu 24.04 | `ci.yml` test-docker job |
-
-## Feature Matrix
-
-| Feature | macOS | Linux | WSL2 |
-|:---|:---:|:---:|:---:|
-| Shell configs (zsh/fish/bash/nu) | ✓ | ✓ | ✓ |
-| Terminal emulator configs | ✓ | ✓ | ✗ (host handles) |
-| Theme engine (K-Means) | ✓ | ✓ | ✓ |
-| Dynamic HEIC dark/light | ✓ native | ⚠ HEIC→PNG converted | ✗ |
-| Neovim + LSP | ✓ | ✓ | ✓ |
-| AI tools (Claude, Codex, etc.) | ✓ | ✓ | ✓ |
-| MCP policy enforcement | ✓ | ✓ | ✓ |
-| Attestation | ✓ | ✓ | ✓ |
-| Fleet (SSH-based) | ✓ | ✓ | ⚠ |
-| AeroSpace (WM) | ✓ | ✗ | ✗ |
-| Niri (WM) | ✗ | ✓ | ✗ |
-| GNOME gsettings | ✗ | ✓ | ⚠ |
-| Build artifact redirect | ✓ | ✓ | ✓ |
-| Self-healing (`dot heal`) | ✓ | ✓ | ✓ |

package/docs/manual/05-appendices/B-security-checklist.md

@@ -1,85 +0,0 @@
----
-render_with_liquid: false
----
-
-# Appendix B: Security Checklist
-
-Run this checklist after a fresh install and quarterly afterwards.
-
-## Pre-Install
-
-- [ ] Download `install.sh` over HTTPS only
-- [ ] Inspect `install.sh` before running (optional, recommended for untrusted environments)
-- [ ] Ensure SSH signing key exists and is backed up (`~/.ssh/id_ed25519`)
-- [ ] Ensure Age key is backed up if reinstalling (`~/.config/age/keys.txt`)
-
-## Post-Install
-
-- [ ] Run `dot doctor` — expect score ≥90
-- [ ] Run `dot verify --security` — all checks pass
-- [ ] Verify commit signing: `cd ~/.dotfiles && git verify-commit HEAD`
-- [ ] Confirm `~/.ssh/allowed_signers` contains your public key
-- [ ] Check that `~/.config/age/keys.txt` permissions are `0600`
-- [ ] Run `dot mcp --strict` — policy matches registry
-
-## Ongoing (monthly)
-
-- [ ] `dot upgrade` — pick up security patches
-- [ ] `dot verify --security` — confirm no new leaks
-- [ ] Review `~/.local/state/dotfiles/mcp-violations.log` — any unexpected entries?
-- [ ] Review recent attestations — `ls ~/.local/state/dotfiles/attestation/ | tail -10`
-- [ ] Rotate Age key if compromised or as part of scheduled rotation
-
-## Ongoing (quarterly)
-
-- [ ] Rotate SSH signing key
-- [ ] Audit `~/.ssh/allowed_signers` — remove former team members
-- [ ] Review SOPS recipient list in `.sops.yaml`
-- [ ] Run `dot chaos` in a test container — verify heal works
-- [ ] Update pinned tool versions in `mise.toml`
-- [ ] Run fleet attestation — confirm all hosts aligned
-
-## Incident Response
-
-If a secret leak is detected:
-
-1. **Contain** — remove from history, force-push
-
-   ```sh
-   git filter-repo --path <file> --invert-paths
-   git push --force
-   ```
-
-2. **Rotate** — change the leaked secret upstream (Stripe key, SSH key, etc.)
-3. **Audit** — check who/what had access
-4. **Notify** — inform affected parties if required
-
-If a host is compromised:
-
-1. **Revoke** — remove the host's public key from `~/.ssh/allowed_signers` on all other fleet hosts
-2. **Re-encrypt** — `sops updatekeys` with the host excluded from recipients
-3. **Attest** — run `dot fleet attest` to verify revocation propagated
-4. **Wipe** — if the host is recoverable, `rm -rf ~/.config/age ~/.dotfiles` and reinstall
-
-## Gates Enforced by CI
-
-Every PR to main must pass:
-
-- [x] SSH-signed commits
-- [x] Shellcheck zero warnings (severity=error)
-- [x] Gitleaks scan
-- [x] Detect-secrets baseline diff
-- [x] TruffleHog verified scan
-- [x] Copyright headers present
-- [x] 100% executable module mapping
-- [ ] 100% measured line and branch coverage (current ratchet is documented in `docs/operations/COVERAGE.md`)
-- [x] Reliability tests (macOS + Ubuntu)
-- [x] Checkov infra scan
-- [x] Version sync (bumped across all files)
-
-## See Also
-
-- [Trust Model](../01-concepts/02-trust-model.md)
-- [Encrypt a Secret tutorial](../02-tutorials/04-encrypt-secret.md)
-- [Security Policy](../../security/SECURITY.md)
-- [Incident Response Playbook](../../security/INCIDENT_RESPONSE.md)