@sebastienrousseau/dotfiles 0.2.499 → 0.2.500

package/docs/manual/04-cookbook/01-recipes.md

@@ -0,0 +1,281 @@
+# Cookbook: Recipes
+
+Thirty short recipes for common tasks.
+
+## Installation & Update
+
+### 1. Install on a fresh machine
+
+```sh
+bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh)"
+```
+
+### 2. Update everything
+
+```sh
+dot upgrade
+```
+
+### 3. Update dotfiles only (no tools)
+
+```sh
+dot update
+```
+
+### 4. Preview what would change
+
+```sh
+dot apply --dry-run
+```
+
+## Themes
+
+### 5. Switch to a specific theme
+
+```sh
+dot theme tahoe-dark
+```
+
+### 6. Toggle between dark and light
+
+```sh
+dot theme toggle
+```
+
+### 7. Open the interactive theme picker
+
+```sh
+dot theme
+```
+
+### 8. List paired wallpaper themes
+
+```sh
+dot theme list
+```
+
+### 9. Add a new wallpaper-driven theme
+
+```sh
+cp my-wallpaper.jpg ~/Pictures/Wallpapers/myname-dark.jpg
+cp my-wallpaper-light.jpg ~/Pictures/Wallpapers/myname-light.jpg
+bash scripts/theme/merge-wallpaper.sh myname
+dot theme rebuild
+dot theme myname-dark
+```
+
+### 10. Regenerate all themes from scratch
+
+```sh
+dot theme rebuild --force
+```
+
+## Configuration
+
+### 11. Edit the source directory
+
+```sh
+dot edit
+```
+
+### 12. Add a new config file to chezmoi
+
+```sh
+dot add ~/.some-config-file
+```
+
+### 13. Remove a managed file
+
+```sh
+dot remove ~/.some-config-file
+```
+
+### 14. Show configuration drift
+
+```sh
+dot status
+```
+
+### 15. Show diff against source
+
+```sh
+dot diff
+```
+
+## Secrets
+
+### 16. Encrypt a new secret file
+
+```sh
+chezmoi add --encrypt ~/some-secret.txt
+```
+
+### 17. Edit an encrypted file
+
+```sh
+sops dot_config/credentials.sops.yaml
+# or
+chezmoi edit ~/some-secret.txt.age
+```
+
+### 18. Rotate your Age key
+
+```sh
+age-keygen -o ~/.config/age/keys.txt.new
+# Update .sops.yaml with new public key
+# Then:
+find . -name '*.sops.yaml' -exec sops updatekeys {} \;
+git commit -sS -am "chore(secrets): rotate age key"
+```
+
+### 19. Check for accidental secret leaks
+
+```sh
+dot verify --security
+```
+
+## Diagnostics
+
+### 20. Quick health check
+
+```sh
+dot doctor
+```
+
+### 21. Auto-fix common issues
+
+```sh
+dot heal
+```
+
+### 22. Check startup performance
+
+```sh
+dot benchmark
+```
+
+### 23. See the health score
+
+```sh
+dot score
+```
+
+### 24. Recent metrics
+
+```sh
+dot metrics
+```
+
+## Fleet
+
+### 25. Attest across all fleet hosts
+
+```sh
+dot fleet attest
+```
+
+### 26. Sync dotfiles to every fleet host
+
+```sh
+dot fleet sync
+```
+
+### 27. Diff config across hosts
+
+```sh
+dot fleet diff
+```
+
+## AI & Agents
+
+### 28. Show installed AI tools
+
+```sh
+dot ai
+```
+
+### 29. Switch agent profile
+
+```sh
+dot mode architect   # or hardener, refactor
+```
+
+### 30. Verify MCP policy
+
+```sh
+dot mcp --strict
+```
+
+## Recovery
+
+### 31. Rollback the last apply
+
+```sh
+dot rollback
+```
+
+### 32. Create an offline bundle
+
+```sh
+dot bundle
+```
+
+### 33. Restore from a bundle
+
+```sh
+dot bundle restore ~/Downloads/dotfiles-bundle-*.tar.zst
+```
+
+## Development
+
+### 34. Run a test locally
+
+```sh
+bash tests/unit/theme/test_themes_toml.sh
+```
+
+### 35. Run all tests
+
+```sh
+./tests/framework/test_runner.sh
+```
+
+### 36. Lint shell scripts
+
+```sh
+dot lint
+```
+
+### 37. Simulate chaos to test self-healing
+
+```sh
+dot chaos symlink   # in an ephemeral container only
+dot heal
+dot doctor
+```
+
+## Manual
+
+### 38. Open the manual in a browser
+
+```sh
+dot manual
+```
+
+### 39. Download the PDF
+
+```sh
+dot manual pdf
+```
+
+### 40. Read the manual in a terminal
+
+```sh
+dot manual text | less
+```
+
+## See Also
+
+- [Troubleshooting](02-troubleshooting.md)
+- [FAQ](03-faq.md)
+- [CLI Reference](../03-reference/01-dot-cli.md)

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

@@ -0,0 +1,319 @@
+# 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/master/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)