@sebastienrousseau/dotfiles 0.2.519 → 0.2.521

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

@@ -1,285 +0,0 @@
----
-render_with_liquid: false
----
-
-# 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/main/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

@@ -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 %}