@sebastienrousseau/dotfiles 0.2.520 → 0.2.521

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

@@ -1,265 +0,0 @@
----
-render_with_liquid: false
----
-{% raw %}
-
-# 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.503"
-
-# 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 = "monterey-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.503",
-  "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 `main` 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)
-{% endraw %}

package/docs/manual/03-reference/03-environment.md

@@ -1,124 +0,0 @@
----
-render_with_liquid: false
----
-
-# Reference: Environment Variables
-
-All environment variables that affect `.dotfiles` behaviour.
-
-## User-Settable
-
-Variables you can set in your shell to change behaviour.
-
-| Variable | Default | Effect |
-|:---|:---|:---|
-| `DOTFILES_VERBOSE` | unset | Verbose output from `dot` commands |
-| `DOTFILES_NONINTERACTIVE` | unset | Skip interactive prompts (for CI) |
-| `DOTFILES_SILENT` | unset | Suppress non-error output |
-| `DOTFILES_DEBUG` | unset | Print shell-init timing to stderr |
-| `DOTFILES_SOURCE_DIR` | `~/.dotfiles` | Override the source directory |
-| `DOTFILES_WALLPAPER_DIR` | `~/Pictures/Wallpapers` | Custom wallpaper directory |
-| `DOTFILES_CACHE_DIR` | `~/.cache/dotfiles` | Override cache location |
-| `DOTFILES_STATE_DIR` | `~/.local/state/dotfiles` | Override state directory |
-| `DOTFILES_TUNING` | `0` | Enable OS tuning (`dot tune`) |
-| `EDITOR` | `nvim` | Editor used by `dot edit` and `sops` |
-| `PAGER` | `less` | Pager used by `dot manual text` |
-
-## Auto-Populated
-
-Variables the dotfiles set in your shell for tool consumption.
-
-| Variable | Value | Source |
-|:---|:---|:---|
-| `XDG_CONFIG_HOME` | `~/.config` | `dot_zshenv` / `dot_config/fish/conf.d/env.fish.tmpl` |
-| `XDG_CACHE_HOME` | `~/.cache` | ditto |
-| `XDG_DATA_HOME` | `~/.local/share` | ditto |
-| `XDG_STATE_HOME` | `~/.local/state` | ditto |
-| `PATH` | managed order | `dot_config/shell/00-core-paths.sh.tmpl` |
-| `BUN_INSTALL` | `~/.bun` | `env.fish.tmpl` |
-| `PIPX_HOME` | `~/.local/share/pipx` | ditto |
-| `PIPX_BIN_DIR` | `~/.local/bin` | ditto |
-| `BUILDS_TMPDIR` | `/tmp/builds` | `dot_zshenv` (created on shell init) |
-| `CARGO_TARGET_DIR` | (from `~/.cargo/config.toml`) | `target-dir = "/tmp/builds/cargo"` |
-| `GOCACHE` | `/tmp/builds/go-cache` | `mise [env]` |
-| `GOTMPDIR` | `/tmp/builds/go-tmp` | `mise [env]` |
-| `PIP_CACHE_DIR` | `/tmp/builds/pip-cache` | `mise [env]` |
-| `UV_CACHE_DIR` | `/tmp/builds/uv-cache` | `mise [env]` |
-| `ZIG_LOCAL_CACHE_DIR` | `/tmp/builds/zig-cache` | `mise [env]` |
-| `ZIG_GLOBAL_CACHE_DIR` | `/tmp/builds/zig-global-cache` | `mise [env]` |
-| `HOMEBREW_PREFIX` | `/opt/homebrew` or `/usr/local` | `dot_zshenv` (macOS) |
-| `MANPATH` | homebrew-adjusted | ditto |
-| `MISE_EXPERIMENTAL` | `1` | `~/.config/mise/config.toml` |
-| `GITHUB_TOKEN` | from `gh auth token` | `~/.config/mise/config.toml` |
-
-## Read by Tools
-
-Variables set by upstream tools and respected by `.dotfiles`.
-
-| Variable | Used for |
-|:---|:---|
-| `SHELL` | Detect default shell |
-| `TERM` | Terminal capabilities (e.g. `xterm-256color`) |
-| `COLORTERM` | True-color detection (`truecolor`) |
-| `LANG` / `LC_ALL` | Locale (must be UTF-8) |
-| `HOME` | User home directory |
-| `USER` | Username |
-| `SSH_AUTH_SOCK` | ssh-agent socket |
-| `GPG_TTY` | GPG pinentry TTY |
-
-## CI-Specific
-
-Variables relevant in GitHub Actions.
-
-| Variable | Purpose |
-|:---|:---|
-| `CI` | Set to `true` in CI; disables prompts |
-| `GITHUB_ACTIONS` | GHA-specific; enables step summary output |
-| `CHEZMOI_VERSION` | Pinned chezmoi version for CI |
-| `COVERAGE_THRESHOLD` | Executable module-mapping threshold (100 in enforced CI; not line coverage) |
-| `DOTFILES_TEST_MODE` | Skip network-dependent tests |
-
-## Secret-Related
-
-| Variable | Purpose |
-|:---|:---|
-| `SOPS_AGE_KEY_FILE` | Override `~/.config/age/keys.txt` path |
-| `SOPS_AGE_RECIPIENTS` | Override recipients for new encryption |
-| `CHEZMOI_AGE_IDENTITY` | Override age identity for chezmoi decrypt |
-
-> Warning: never set these to values stored in plaintext config. Use a password manager or ephemeral injection.
-
-## Startup Order
-
-Shell-loaded variables follow this precedence (later wins):
-
-1. System defaults (`/etc/environment`, `/etc/profile`)
-2. Homebrew shellenv (macOS)
-3. `~/.zshenv` (earliest user-level file; sets XDG + PATH bootstrap)
-4. `~/.zprofile` or `~/.config/fish/conf.d/*.fish`
-5. `~/.zshrc` or `~/.config/fish/config.fish`
-6. `mise activate` — injects tool-specific env
-7. Per-project `.envrc` via direnv (opt-in)
-
-To debug: `DOTFILES_DEBUG=1 zsh -i -c exit` prints timing for each stage.
-
-## Unsetting
-
-To clean up environment pollution:
-
-```sh
-# Show current dotfiles-set vars
-env | grep -E '^(DOTFILES_|XDG_|BUILDS_)'
-
-# Unset one
-unset DOTFILES_DEBUG
-
-# Reset to defaults (restart shell)
-exec $SHELL -l
-```
-
-## See Also
-
-- [Configuration Files](02-config-files.md)
-- [Feature Flags](05-feature-flags.md)
-- [First Install](../02-tutorials/01-first-install.md)

package/docs/manual/03-reference/04-templates.md

@@ -1,190 +0,0 @@
----
-render_with_liquid: false
----
-{% raw %}
-
-# Reference: Template Variables
-
-Every variable available to chezmoi templates (`.tmpl` files).
-
-## From `.chezmoidata.toml`
-
-Flat top-level keys:
-
-| Variable | Type | Example |
-|:---|:---|:---|
-| `.dotfiles_version` | string | `"0.2.501"` |
-| `.theme` | string | `"tahoe-dark"` |
-| `.machine` | string | `"macbook-t2"` |
-| `.profile` | string | `"laptop"` |
-| `.default_shell` | string | `"fish"` |
-| `.terminal_font_family` | string | `"JetBrainsMono Nerd Font"` |
-| `.terminal_font_size` | int | `12` |
-| `.name` | string | `"Your Name"` |
-| `.email` | string | `"you@example.com"` |
-
-## From `.chezmoidata/themes.toml`
-
-```go
-{{- $t := index .themes .theme }}
-{{ $t.mode }}              // "dark" or "light"
-{{ $t.family }}            // "tahoe"
-{{ $t.macos_accent }}      // 4 (integer)
-{{ $t.term.bg }}           // "#121430"
-{{ $t.term.fg }}           // "#d4d8ec"
-{{ $t.term.c0 }} .. {{ $t.term.c15 }}   // ANSI 0-15
-{{ $t.ui.accent }}         // "#3951b1"
-{{ $t.ui.accent_text }}    // "#ffffff"
-{{ $t.ui.panel }}
-{{ $t.ui.border }}
-{{ $t.app.nvim }}          // "catppuccin"
-{{ $t.app.starship_palette }}
-```
-
-## From `.chezmoidata/hardware.toml`
-
-```go
-{{- $hw := index .hardware .machine }}
-{{ $hw.display_scale }}    // 2.0
-{{ $hw.kbd_layout }}       // "qwerty"
-{{ $hw.modifier_mode }}    // "left-cmd-control"
-{{ $hw.perf_profile }}     // "laptop"
-{{ $hw.wm }}               // "aerospace"
-{{ $hw.features.touchid }} // bool
-```
-
-## From Feature Flags
-
-```go
-{{- $f := mergeOverwrite .features $hw.features }}
-{{ if $f.dms }}
-# Dank Material Shell-specific config
-{{ end }}
-
-{{ if $f.niri }}
-# Niri WM config
-{{ end }}
-```
-
-## Built-in Chezmoi Variables
-
-```go
-{{ .chezmoi.os }}                // "darwin" | "linux" | "windows"
-{{ .chezmoi.arch }}              // "amd64" | "arm64"
-{{ .chezmoi.kernel }}            // "Darwin" | "Linux"
-{{ .chezmoi.kernel.ostype }}     // "darwin24" etc
-{{ .chezmoi.hostname }}          // host machine hostname
-{{ .chezmoi.username }}          // current user
-{{ .chezmoi.homeDir }}           // $HOME
-{{ .chezmoi.sourceDir }}         // ~/.dotfiles
-{{ .chezmoi.workingTree }}       // git working tree root
-{{ .chezmoi.executable }}        // chezmoi binary path
-{{ .chezmoi.osRelease }}         // Linux /etc/os-release data
-```
-
-## Built-in Chezmoi Functions
-
-```go
-{{ exec "command" | trim }}
-{{ output "hostname" }}
-{{ include "path/to/file" }}
-{{ decrypt "path/to/file.age" }}
-{{ sopsDecrypt "path/to/file.sops.yaml" | fromYaml }}
-{{ joinPath "a" "b" }}
-{{ stat "/path" }}
-{{ ioreg ".." ".." }}             // macOS only
-{{ lookPath "command" }}           // returns path or empty
-```
-
-## Helper Templates (in `.chezmoitemplates/`)
-
-Reusable partials included via:
-
-```go
-{{ template "paths/00-default.paths.sh" . }}
-{{ template "aliases/cd.aliases.sh" . }}
-{{ template "functions/cdls.sh" . }}
-```
-
-Available partials:
-
-- `paths/00-default.paths.sh` — canonical PATH construction
-- `paths/05-pipx.paths.sh` — pipx + ~/.local/bin
-- `paths/99-custom.paths.sh` — user-appended paths
-- `aliases/*.aliases.sh` — per-domain alias sets
-- `functions/*.sh` — reusable shell functions
-
-## Example: Using Theme in Ghostty Config
-
-```go
-{{- /* dot_config/ghostty/config.tmpl */ -}}
-{{- $t := index .themes .theme -}}
-
-font-family = "{{ .terminal_font_family }}"
-font-size = {{ .terminal_font_size }}
-
-background = {{ $t.term.bg }}
-foreground = {{ $t.term.fg }}
-cursor-color = {{ $t.term.cursor }}
-
-palette = 0={{ $t.term.c0 }}
-palette = 1={{ $t.term.c1 }}
-palette = 2={{ $t.term.c2 }}
-# ... through 15
-
-{{- if eq .chezmoi.os "darwin" }}
-macos-titlebar-style = transparent
-{{- end }}
-```
-
-## Example: Platform × Preset
-
-```go
-{{- $hw := index .hardware .machine -}}
-
-{{- if and (eq .chezmoi.os "darwin") (eq $hw.wm "aerospace") }}
-# macOS AeroSpace config
-include = ["aerospace-macos.toml"]
-{{- else if and (eq .chezmoi.os "linux") (eq $hw.wm "niri") }}
-# Linux Niri config
-include = ["niri.kdl"]
-{{- end }}
-
-# DPI-aware sizing
-font-size = {{ mul 8 $hw.display_scale | int }}
-```
-
-## Template Testing
-
-Render a template without applying:
-
-```sh
-chezmoi execute-template < dot_config/ghostty/config.tmpl
-```
-
-Or test an expression:
-
-```sh
-chezmoi execute-template '{{ .chezmoi.os }}'
-# darwin
-
-chezmoi execute-template '{{- $t := index .themes .theme -}}{{ $t.term.bg }}'
-# #121430
-```
-
-## Validation in CI
-
-Every push to main runs:
-
-```sh
-chezmoi apply --dry-run
-```
-
-If any template fails to render, the build breaks before merge.
-
-## See Also
-
-- [Chezmoi template reference](https://www.chezmoi.io/reference/templates/)
-- [Configuration Files](02-config-files.md)
-- [Create a Profile tutorial](../02-tutorials/03-create-profile.md)
-{% endraw %}