@sebastienrousseau/dotfiles 0.2.499 → 0.2.500

package/docs/manual/02-tutorials/05-deploy-fleet.md

@@ -0,0 +1,279 @@
+# Tutorial: Deploy to a Fleet
+
+Roll out `.dotfiles` across multiple workstations and verify they're in sync.
+
+## Scenario
+
+You have three hosts:
+
+- **macbook-t2** — your MacBook (current host, already installed)
+- **surface-pro** — your Linux laptop (new install)
+- **geekom-a9** — your desktop NUC (new install)
+
+Goal: all three running identical `.dotfiles` with per-host customization, with auditable cross-host attestation.
+
+## Step 1: Per-Host Install
+
+On each new host:
+
+```sh
+bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh)"
+```
+
+During `chezmoi init`, answer with the host's preset:
+
+- Surface Pro → `machine = "surface-pro"`
+- Geekom A9 → `machine = "geekom-a9"`
+
+## Step 2: Exchange Signing Keys
+
+Each host has its own SSH ED25519 key. To verify commits and attestations across the fleet, publish each host's public key to every other host.
+
+**On each host, copy the public key:**
+
+```sh
+cat ~/.ssh/id_ed25519.pub
+# ssh-ed25519 AAAAC3N...jkl5 user@macbook-t2
+```
+
+**Collect all three keys. Append them to `~/.ssh/allowed_signers` on every host:**
+
+```
+user@macbook-t2 ssh-ed25519 AAAAC3N...jkl5
+user@surface-pro ssh-ed25519 AAAAC3N...abc7
+user@geekom-a9 ssh-ed25519 AAAAC3N...def9
+```
+
+Optionally commit `allowed_signers` as a template so all hosts receive updates via `dot update`:
+
+```sh
+# On macbook-t2
+chezmoi add ~/.ssh/allowed_signers
+git add -A && git commit -sS -m "feat(ssh): add fleet signing keys"
+git push
+```
+
+Now every other host gets the updated list on `dot update`.
+
+## Step 3: Share the Age Key (for Shared Secrets)
+
+If you want shared secrets decrypted on all three hosts, each host must have an Age key recipient in `.sops.yaml`.
+
+Option A: Share one key across all hosts (simpler, less granular).
+Option B: Each host has its own key; all three are listed as recipients (better operational security).
+
+For Option B:
+
+```sh
+# On macbook-t2 (already set up)
+grep "public key:" ~/.config/age/keys.txt
+
+# On surface-pro
+age-keygen -o ~/.config/age/keys.txt
+grep "public key:" ~/.config/age/keys.txt
+
+# On geekom-a9
+age-keygen -o ~/.config/age/keys.txt
+grep "public key:" ~/.config/age/keys.txt
+```
+
+Add all three public keys to `.sops.yaml`:
+
+```yaml
+creation_rules:
+  - path_regex: \.sops\.yaml$
+    age: >-
+      age1aaa...111,    # macbook-t2
+      age1bbb...222,    # surface-pro
+      age1ccc...333     # geekom-a9
+```
+
+Re-encrypt existing secrets for the new recipients:
+
+```sh
+# On macbook-t2
+find . -name '*.sops.yaml' -exec sops updatekeys {} \;
+git add .sops.yaml dot_config/*.sops.yaml
+git commit -sS -m "chore(secrets): add fleet recipients"
+git push
+```
+
+Other hosts on `dot update` decrypt with their own private key automatically.
+
+## Step 4: Verify Fleet Alignment
+
+From any host:
+
+```sh
+dot fleet attest
+```
+
+Expected output:
+
+```
+Fleet Attestation — v0.2.500
+
+Host           Git SHA    Policy    Tools OK   Drift   Verified
+-------------- ---------- --------- ---------- ------- --------
+macbook-t2     abc123d    0x7f2a…   ✓          0       ✓
+surface-pro    abc123d    0x7f2a…   ✓          0       ✓
+geekom-a9      abc123d    0x7f2a…   ✓          0       ✓
+-------------- ---------- --------- ---------- ------- --------
+FLEET STATUS: 3/3 aligned
+```
+
+If any row shows drift or missing verification:
+
+```sh
+# Check which host is out of sync
+dot fleet diff
+
+# SSH into the affected host and fix
+ssh surface-pro
+dot doctor && dot heal
+dot update
+```
+
+## Step 5: Per-Host Customization
+
+Each host has its own `~/.config/chezmoi/chezmoi.toml` — use it for things that shouldn't propagate:
+
+```toml
+# surface-pro's chezmoi.toml
+[data]
+machine = "surface-pro"
+theme = "dome-dark"           # per-host default
+default_shell = "fish"
+terminal_font_size = 11       # smaller for HiDPI
+```
+
+```toml
+# geekom-a9's chezmoi.toml
+[data]
+machine = "geekom-a9"
+theme = "valley-dark"         # different default
+default_shell = "zsh"
+terminal_font_size = 14       # larger for external 1440p
+```
+
+Both hosts render from the same templates, producing correct platform-appropriate output.
+
+## Step 6: Fleet-Wide Updates
+
+When you push a commit to master, each host pulls independently:
+
+```sh
+# On each host
+dot update
+```
+
+`dot update` does:
+
+1. `git pull --rebase --autostash` in `~/.dotfiles`
+2. `chezmoi apply` with progress output
+3. `dot heal` if apply detected drift
+4. Reports changes applied
+
+For simultaneous update across the fleet (requires SSH):
+
+```sh
+dot fleet sync
+# Connects to each host in parallel
+# Runs `dot update` via SSH
+# Collects outcomes
+```
+
+## Step 7: Secrets Rotation
+
+When a secret is compromised (or as part of routine rotation):
+
+```sh
+# 1. Edit the secret on any host
+sops dot_config/credentials.sops.yaml
+# Change the compromised value, save
+
+# 2. Commit and push
+git commit -sS -am "chore(secrets): rotate stripe key"
+git push
+
+# 3. All fleet hosts pick up the new value on next update
+# On each host:
+dot update
+```
+
+Since hosts all have the Age private key for themselves, decryption is automatic.
+
+## Step 8: Decommission a Host
+
+When retiring a host:
+
+```sh
+# 1. Remove the host's public key from allowed_signers
+# Edit dot_ssh/allowed_signers.tmpl (on any host)
+
+# 2. Remove the host's Age public key from .sops.yaml
+
+# 3. Re-encrypt all SOPS files (remove the decommissioned recipient)
+find . -name '*.sops.yaml' -exec sops updatekeys {} \;
+
+# 4. Commit
+git commit -sS -am "chore(fleet): decommission geekom-a9"
+git push
+
+# 5. On the decommissioned host: wipe the dotfiles state
+rm -rf ~/.dotfiles ~/.local/bin/dot ~/.config/chezmoi ~/.config/age
+```
+
+## Troubleshooting
+
+### "Fleet host unreachable"
+
+`dot fleet` couldn't SSH to a host. Check:
+
+```sh
+ssh surface-pro 'dot version'
+# If this fails, fix SSH connectivity first
+```
+
+### Drift on One Host
+
+Run `dot heal` on that host:
+
+```sh
+ssh surface-pro 'dot heal'
+```
+
+If drift persists:
+
+```sh
+ssh surface-pro 'chezmoi diff | head -50'
+# Inspect what's different
+```
+
+### Policy Hash Mismatch
+
+One host has an older policy than the others. Usually means that host missed an update:
+
+```sh
+ssh surface-pro 'dot update'
+```
+
+### Attestation Signature Failed
+
+The host's SSH key isn't in `~/.ssh/allowed_signers` on the verifying host. Fix by redistributing `allowed_signers`.
+
+## Summary
+
+A three-host fleet:
+
+- Installs from one repository
+- Has independent signing keys (each host verifies commits from others)
+- Can share secrets across specific hosts via SOPS recipients
+- Is auditable via `dot fleet attest`
+- Updates independently with `dot update` (or in parallel with `dot fleet sync`)
+
+## Next
+
+- [Concept: Fleet Architecture](../01-concepts/04-fleet.md)
+- [Reference: Fleet Commands](../03-reference/01-dot-cli.md#fleet)
+- [Operations: Fleet Deployment](../../architecture/fleet-deployment.md)

package/docs/manual/03-reference/01-dot-cli.md

@@ -0,0 +1,413 @@
+# Reference: The `dot` CLI
+
+Complete command reference. Every subcommand, every flag, every exit code.
+
+## Invocation
+
+```
+dot [<command>] [<subcommand>] [<flags>] [<args>]
+```
+
+With no arguments, `dot` prints the overview (same as `dot help`).
+
+## Global Flags
+
+| Flag | Purpose |
+|:---|:---|
+| `-h`, `--help` | Show help for the command (or overview if no command given) |
+| `-v`, `--verbose` | Verbose output |
+| `--version` | Print the dotfiles version and exit |
+| `--json` | Machine-readable JSON output (where supported) |
+
+## Start Here
+
+### `dot sync` / `dot apply`
+
+Apply the tracked configuration to the machine. Aliases: `dot sync == dot apply`.
+
+```
+dot sync [--dry-run|-n] [--force|-f] [--verbose|-v]
+```
+
+| Flag | Effect |
+|:---|:---|
+| `--dry-run`, `-n` | Preview changes without applying |
+| `--force`, `-f` | Skip confirmation prompts |
+| `--verbose`, `-v` | Show per-file actions |
+
+Exit codes: 0 (clean apply), 1 (drift reconciled), 2 (apply failed).
+
+### `dot doctor`
+
+Check the environment and surface issues.
+
+```
+dot doctor [--score|-s] [--heal|-H] [--json|-j] [--verbose|-v]
+```
+
+| Flag | Effect |
+|:---|:---|
+| `--score`, `-s` | Print numeric score (0-100) only |
+| `--heal`, `-H` | Auto-fix detected issues |
+| `--json`, `-j` | Machine-readable output |
+| `--verbose`, `-v` | Show every check (default: failures only) |
+
+Exit codes: 0 (healthy), 1 (warnings), 2 (critical failures).
+
+### `dot learn`
+
+Interactive guided tour of the environment. Takes ~5-10 minutes, covers shells, secrets, themes, performance, security. Press `q` to exit at any time.
+
+### `dot help [<command>]`
+
+Show the overview (no arg) or detailed help for a specific command.
+
+## Daily Use
+
+### `dot status` / `dot diff`
+
+Show local drift or preview pending changes.
+
+```
+dot status            # list changed managed files
+dot diff [<path>]     # show unified diff (all or one path)
+```
+
+### `dot edit`
+
+Open the source directory in `$EDITOR`. Shorthand for `cd ~/.dotfiles && $EDITOR`.
+
+### `dot upgrade`
+
+Update tools, plugins, and dotfiles.
+
+```
+dot upgrade [--tools-only] [--dotfiles-only]
+```
+
+Runs `topgrade`-style upgrade of Mise tools, Nix flakes, homebrew (macOS), and pulls the latest `.dotfiles`.
+
+### `dot commit`
+
+Create an AI-assisted conventional commit from staged changes.
+
+```
+dot commit
+```
+
+Uses the configured AI provider (via `dot mode`) to generate a commit message matching the Conventional Commits spec.
+
+### `dot search <term>`
+
+Find commands by keyword.
+
+```
+dot search theme      # lists all theme-related commands
+dot search secret     # lists all secret-related commands
+```
+
+## Inspect & Repair
+
+### `dot heal`
+
+Auto-repair missing tools, chezmoi drift, broken symlinks, and critical files.
+
+```
+dot heal [--dry-run|-n] [--force|-f] [--tool <name>]
+```
+
+See [Self-Healing concept](../01-concepts/05-self-healing.md).
+
+### `dot rollback`
+
+Return to a previous snapshot.
+
+```
+dot rollback              # restore most recent snapshot
+dot rollback status       # list snapshots
+dot rollback restore <n>  # restore snapshot #n
+dot rollback clean        # delete snapshots older than 30 days
+```
+
+### `dot chaos`
+
+Simulate corruption to test self-healing. **Destructive.** Use only in ephemeral environments.
+
+```
+dot chaos [symlink|config|tool|permission|all]
+```
+
+### `dot attest`
+
+Export signed workstation evidence (see [Trust Model](../01-concepts/02-trust-model.md)).
+
+```
+dot attest [--output|-o <file>] [--sign|-s]
+```
+
+Default output: `~/.local/state/dotfiles/attestation/YYYY-MM-DD-HHMMSS.json`. With `--sign`, the JSON is signed with the user's SSH ED25519 key.
+
+### `dot verify`
+
+Verify integrity of the installation.
+
+```
+dot verify [--security|-s] [--attestation <path>]
+```
+
+| Flag | Effect |
+|:---|:---|
+| `--security`, `-s` | Run gitleaks + signature checks + policy hash |
+| `--attestation <path>` | Verify an external attestation file |
+
+### `dot lint`
+
+Lint shell scripts (shellcheck, shfmt).
+
+```
+dot lint [--path <glob>] [--strict]
+```
+
+## Performance
+
+### `dot benchmark`
+
+Measure shell startup time.
+
+```
+dot benchmark [--detailed|-d] [--profile|-p] [--compare|-c] [--waterfall|-w] [--runs|-r <n>]
+```
+
+| Flag | Effect |
+|:---|:---|
+| `--detailed`, `-d` | Per-module timing breakdown |
+| `--profile`, `-p` | Profile with `$SHELL -ixc ""` |
+| `--compare`, `-c` | Compare against baseline |
+| `--waterfall`, `-w` | Waterfall visualization |
+| `--runs`, `-r <n>` | Number of hyperfine runs (default 10) |
+
+Exit codes: 0 (<500ms target), 1 (regression).
+
+### `dot perf`
+
+Quick performance snapshot.
+
+```
+dot perf [--json|-j] [--profile|-p] [--runs|-r <n>] [--target|-t <ms>]
+```
+
+### `dot prewarm`
+
+Regenerate shell init caches for fast startup.
+
+### `dot cache-refresh`
+
+Rebuild generated shell state (cold-start alternative to prewarm).
+
+### `dot clean-cache`
+
+Clear generated shell initialization caches. Next shell startup will be slow; use `dot prewarm` afterward.
+
+### `dot score`
+
+Show system health + security score.
+
+### `dot metrics`
+
+Show recent observability metrics (startup times, heal events, score history).
+
+### `dot load-bench`
+
+Measure heavy-layer (nvm, rbenv, direnv) readiness time.
+
+## AI & Agents
+
+### `dot ai`
+
+Show installed AI tools with versions and status.
+
+```
+dot ai
+```
+
+### `dot mcp`
+
+Inspect MCP policy and registry.
+
+```
+dot mcp [--strict|-s] [--json|-j]
+```
+
+With `--strict`, validates the active MCP registry matches the policy hash. Exit code 1 on mismatch.
+
+### `dot mode [<profile>]`
+
+Show or set the agent profile.
+
+```
+dot mode              # show current profile
+dot mode architect    # switch to architect profile
+dot mode list         # list all profiles
+```
+
+Available profiles (see `dot_config/ai/patterns/`): `architect`, `hardener`, `refactor`. Custom profiles can be added by dropping `<name>.md` in the patterns directory.
+
+### `dot agent`
+
+Agent metadata, logs, checkpoints, and conformance reports.
+
+```
+dot agent status              # current agent state
+dot agent logs [--since <t>]  # recent agent invocations
+dot agent conformance         # MCP policy conformance report
+```
+
+## Configuration
+
+### `dot theme`
+
+Switch terminal and desktop themes. See [Theme Engine](../01-concepts/03-theme-engine.md) and [Theming Guide](../../guides/THEMING.md).
+
+```
+dot theme              # interactive picker
+dot theme <name>       # switch directly (e.g. dot theme tahoe-dark)
+dot theme toggle       # swap dark↔light within family
+dot theme list         # show paired themes with System/Custom source
+dot theme rebuild [--force|--list]  # regenerate from wallpapers
+```
+
+### `dot env`
+
+Show managed tool versions.
+
+```
+dot env               # all managed tools
+dot env <tool>        # single tool
+```
+
+### `dot profile [<name>]`
+
+Show or switch the active profile.
+
+```
+dot profile           # show active profile
+dot profile list      # all profiles
+dot profile laptop    # switch to 'laptop' profile
+```
+
+Profiles live in `.chezmoidata.toml` under `[profiles.<name>]`.
+
+### `dot secrets`
+
+Edit or manage encrypted secrets.
+
+```
+dot secrets list              # all encrypted files
+dot secrets edit <path>       # open in $EDITOR (decrypted)
+dot secrets rotate            # re-encrypt with current recipients
+dot secrets verify            # integrity check (no decryption)
+```
+
+## Fleet
+
+### `dot fleet`
+
+Multi-node status, drift, and namespace.
+
+```
+dot fleet              # show all known hosts
+dot fleet attest       # collect signed attestations
+dot fleet diff         # compare rendered config across hosts
+dot fleet sync         # run `dot update` on every host
+```
+
+Fleet hosts are configured in `~/.config/dotfiles/fleet.toml`.
+
+## Reference
+
+### `dot version`
+
+Show the installed version.
+
+```
+dot version [--json]
+```
+
+### `dot manual`
+
+Open or download the manual in multiple formats.
+
+```
+dot manual            # open latest HTML manual in browser
+dot manual pdf        # download + open PDF
+dot manual text       # pipe ASCII text to pager
+dot manual download <format>  # save to current directory
+dot manual --offline  # use bundled offline copy (from `dot bundle`)
+```
+
+Formats: `html`, `html-multi`, `pdf`, `epub`, `text`, `markdown`.
+
+### `dot add <path>`
+
+Import a file into chezmoi's source directory.
+
+```
+dot add ~/.somefile                    # plaintext
+dot add --encrypt ~/.somefile          # encrypted with Age
+dot add --template ~/.somefile         # templatize
+```
+
+### `dot remove <path>`
+
+Safely remove a managed file (removes from source and unmanages).
+
+### `dot cd`
+
+Print the source directory path. Useful for `cd $(dot cd)`.
+
+### `dot bundle`
+
+Create an offline portable archive.
+
+```
+dot bundle                        # default output ~/Downloads/
+dot bundle --to <dir|file>        # custom location
+dot bundle --manual               # include offline manual
+dot bundle restore <bundle.tar.zst>  # restore from bundle
+```
+
+### `dot packages`
+
+Show installed packages and package managers.
+
+```
+dot packages
+dot packages --manager mise|nix|brew|apt
+```
+
+## Environment Variables
+
+| Variable | Purpose |
+|:---|:---|
+| `DOTFILES_VERBOSE=1` | Verbose output for all `dot` commands |
+| `DOTFILES_NONINTERACTIVE=1` | Skip interactive prompts |
+| `DOTFILES_SILENT=1` | Suppress non-error output |
+| `DOTFILES_SOURCE_DIR` | Override the source directory |
+| `DOTFILES_WALLPAPER_DIR` | Override `~/Pictures/Wallpapers/` |
+| `DOTFILES_DEBUG=1` | Print timing info during shell init |
+
+## Exit Codes
+
+| Code | Meaning |
+|:---|:---|
+| 0 | Success |
+| 1 | Warnings or recoverable errors |
+| 2 | Critical failure — manual intervention required |
+| 127 | Command not found |
+
+## See Also
+
+- [Configuration Files Reference](02-config-files.md)
+- [Environment Reference](03-environment.md)
+- [Template Variables](04-templates.md)
+- [Feature Flags](05-feature-flags.md)