@sebastienrousseau/dotfiles 0.2.481 → 0.2.500

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)

package/docs/manual/03-reference/02-config-files.md

@@ -0,0 +1,259 @@
+# Reference: Configuration Files
+
+Every config file read or written by `.dotfiles`, with its schema and purpose.
+
+## Source Repository
+
+| File | Purpose |
+|:---|:---|
+| `~/.dotfiles/.chezmoidata.toml` | Global defaults: theme, profile, version, features |
+| `~/.dotfiles/.chezmoidata/hardware.toml` | Machine presets (MacBook T2, Surface Pro, etc.) |
+| `~/.dotfiles/.chezmoidata/themes.toml` | **Generated** theme palettes — do not edit |
+| `~/.dotfiles/.chezmoidata/keybinds.toml` | Modifier hierarchy matrix |
+| `~/.dotfiles/mise.toml` | Pinned runtime versions for the dotfiles repo |
+| `~/.dotfiles/.chezmoiignore` | Paths excluded from `chezmoi apply` |
+| `~/.dotfiles/.chezmoitemplates/` | Reusable template partials |
+
+## User-Owned Configuration
+
+| File | Purpose | Git-tracked? |
+|:---|:---|:---:|
+| `~/.config/chezmoi/chezmoi.toml` | Per-host overrides (machine, theme, shell) | No |
+| `~/.config/age/keys.txt` | Age private key for decryption | No |
+| `~/.config/mise/config.toml` | User runtime preferences (managed by this repo) | Via chezmoi |
+| `~/.config/dotfiles/fleet.toml` | Fleet host list (optional) | No |
+| `~/.ssh/allowed_signers` | SSH public keys trusted for commit verification | Via chezmoi (template) |
+
+## `.chezmoidata.toml` Schema
+
+```toml
+# Version — bumped by version-sync.sh at release time
+dotfiles_version = "0.2.500"
+
+# Machine preset — override in ~/.config/chezmoi/chezmoi.toml per host
+machine = ""
+
+# Active theme — see `dot theme list`
+theme = "tahoe-dark"
+
+# Terminal defaults
+terminal_font_family = "JetBrainsMono Nerd Font"
+terminal_font_size = 12
+default_shell = "fish"     # fish | zsh | nu
+
+# Git identity (prompt-provided via chezmoi init)
+name = ""
+email = ""
+
+# Active profile
+profile = "laptop"         # desktop | laptop | server | codespace
+
+# Feature flags (see 05-feature-flags.md)
+[features]
+dms = false
+linux_desktop = false
+niri = false
+waybar = false
+
+# Profiles (named collections of overrides)
+[profiles.desktop]
+# ...
+
+[profiles.laptop]
+# ...
+```
+
+## `.chezmoidata/hardware.toml` Schema
+
+```toml
+[hardware.<preset-name>]
+display_scale = 1.0 | 1.25 | 1.5 | 1.75 | 2.0
+kbd_layout = "qwerty" | "colemak-dh" | "dvorak"
+modifier_mode = "standard" | "left-cmd-control" | "fn-swap"
+perf_profile = "desktop" | "laptop" | "low-power"
+wm = "aerospace" | "niri" | "gnome" | "kde" | "none"
+
+[hardware.<preset-name>.features]
+# Per-preset feature overrides (merged on top of .chezmoidata.toml features)
+<flag> = <bool>
+```
+
+## `.chezmoidata/themes.toml` Schema
+
+**Generated by `dot theme rebuild` — do not edit manually.**
+
+```toml
+[themes.<name>]
+mode = "dark" | "light"
+family = "<family-name>"
+macos_accent = -1 .. 6     # -1=Graphite, 0=Red, 1=Orange, 2=Yellow, 3=Green, 4=Blue, 5=Purple, 6=Pink
+wallpaper = "/absolute/path/to/wallpaper.heic"
+source = "custom" | "system"
+
+[themes.<name>.term]
+bg, fg, cursor, cursor_text, sel_bg, sel_fg  # hex RGB
+c0 .. c15                                    # 16 ANSI colors
+
+[themes.<name>.ui]
+accent, accent_text     # WCAG AAA enforced (7:1)
+error, warning, success, info
+panel                   # 1.03-2.0 contrast vs bg
+border                  # 1.08-3.5 contrast vs bg
+
+[themes.<name>.app]
+nvim, nvim_style, lualine
+gtk_theme, gtk_icon, gnome_shell, gnome_gtk
+vscode, vscode_dark, vscode_light
+cat_wallpaper
+starship_palette
+```
+
+See [Theme Engine concept](../01-concepts/03-theme-engine.md) for how values are derived.
+
+## `~/.config/chezmoi/chezmoi.toml` (Per-Host)
+
+```toml
+sourceDir = "/Users/you/.dotfiles"
+
+[data]
+machine = "surface-pro"      # selects preset from hardware.toml
+theme = "dome-dark"          # overrides .chezmoidata.toml default
+default_shell = "fish"
+terminal_font_size = 11
+email = "you@example.com"
+name = "Your Name"
+```
+
+Fields here override same-named fields in `.chezmoidata.toml` at render time.
+
+## `~/.dotfiles/mise.toml` (Pinned Versions)
+
+Strict versions for testing the repo itself (separate from the user's own mise config):
+
+```toml
+[tools]
+chezmoi = "2.47.1"
+pandoc = "3.1.8"
+shellcheck = "0.10.0"
+shfmt = "3.8.0"
+# ...
+
+[env]
+# Repo-level env vars
+```
+
+## `~/.config/mise/config.toml` (User)
+
+Managed by this repo via chezmoi. Lists all CLI tools + language runtimes:
+
+```toml
+[settings]
+auto_install = true
+activate_aggressive = true
+
+[tools]
+node = ["lts", "24", "25"]
+python = ["3.12", "3.11"]
+go = "latest"
+rust = "latest"
+# ... 60+ tools
+
+[env]
+MISE_EXPERIMENTAL = "1"
+GITHUB_TOKEN = "{{exec(command='gh auth token')}}"
+GOCACHE = "/tmp/builds/go-cache"
+PIP_CACHE_DIR = "/tmp/builds/pip-cache"
+UV_CACHE_DIR = "/tmp/builds/uv-cache"
+ZIG_LOCAL_CACHE_DIR = "/tmp/builds/zig-cache"
+ZIG_GLOBAL_CACHE_DIR = "/tmp/builds/zig-global-cache"
+```
+
+## `~/.cargo/config.toml` (Managed)
+
+```toml
+[build]
+jobs = -1
+incremental = true
+target-dir = "/tmp/builds/cargo"
+```
+
+## `~/.ssh/allowed_signers`
+
+Template: `dot_ssh/allowed_signers.tmpl`
+
+Lists SSH public keys authorized to sign commits in the repository:
+
+```
+you@example.com ssh-ed25519 AAAAC3N...
+teammate@example.com ssh-ed25519 AAAAC3N...
+```
+
+## `dot_config/dotfiles/mcp.json`
+
+MCP policy and registry. See [MCP Policy reference](../../security/MCP_POLICY.md).
+
+```json
+{
+  "policy_version": "2026-01",
+  "allowed_servers": ["fs", "shell", "github"],
+  "denied_tools": ["network.raw"],
+  "attestation_required": true,
+  "registry": {
+    "servers": [
+      {"name": "fs", "command": "...", "hash": "..."},
+      ...
+    ]
+  }
+}
+```
+
+## `dot_config/dotfiles/agent-card.json`
+
+Agent Card (MCP A2A spec):
+
+```json
+{
+  "name": "dotfiles-agent",
+  "version": "0.2.500",
+  "capabilities": ["chezmoi.apply", "theme.switch", "secrets.decrypt"],
+  "policy_hash": "0x7f2a..."
+}
+```
+
+## Log Files
+
+| Path | Content | Rotation |
+|:---|:---|:---|
+| `~/.local/state/dotfiles/install.log` | Installer output | Never rotated |
+| `~/.local/state/dotfiles/heal.log` | Heal attempts | Append-only |
+| `~/.local/state/dotfiles/metrics.jsonl` | Observability events | Rotated at 10MB |
+| `~/.local/state/dotfiles/mcp-violations.log` | MCP policy violations | Rotated at 10MB |
+| `~/.local/state/dotfiles/attestation/*.json` | Attestation snapshots | 90-day retention |
+| `~/.local/state/dotfiles/snapshots/*` | Rollback snapshots | 30-day retention |
+
+## Cache Files
+
+| Path | Content | Invalidation |
+|:---|:---|:---|
+| `~/.cache/shell/*-init.sh` | Pre-generated shell init output | Binary mtime |
+| `~/.cache/dotfiles/themes/*.toml` | Per-wallpaper theme cache | Wallpaper mtime |
+| `~/.cache/dotfiles/manual/*` | Downloaded manual files | Version change |
+| `~/.cache/gitstatus/*` | Starship gitstatus | Auto |
+
+## Verified Files
+
+Every commit on `master` modifies tracked files only. Untracked files in the source directory (e.g. editor swap files) are ignored via `.chezmoiignore`:
+
+```
+.DS_Store
+.vscode/
+*.swp
+_build/
+```
+
+## See Also
+
+- [Environment Reference](03-environment.md)
+- [Template Variables](04-templates.md)
+- [Feature Flags](05-feature-flags.md)
+- [First Install Tutorial](../02-tutorials/01-first-install.md)