---
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 = "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.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 `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)
{% endraw %}