{% 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¶
# 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¶
[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.
[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 for how values are derived.
~/.config/chezmoi/chezmoi.toml (Per-Host)¶
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 = "[email protected]"
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):
[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:
[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)¶
~/.ssh/allowed_signers¶
Template: dot_ssh/allowed_signers.tmpl
Lists SSH public keys authorized to sign commits in the repository:
[email protected] ssh-ed25519 AAAAC3N...
[email protected] ssh-ed25519 AAAAC3N...
dot_config/dotfiles/mcp.json¶
MCP policy and registry. See MCP Policy reference.
{
"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):
{
"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: