# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this repo is

Personal dotfiles managed with [chezmoi](https://chezmoi.io). This directory (`~/.local/share/chezmoi`) is chezmoi's *source* directory — files here use chezmoi's naming conventions and are rendered/installed into `$HOME` on the target machine, they are not consumed directly from this path.

**Use the `chezmoi` skill (`.claude/skills/chezmoi-skill/SKILL.md`) for any work in this repo.** It covers chezmoi's source-file naming conventions (`dot_`, `private_`, `executable_`, `.tmpl`), machine-specific templating patterns, the required `chezmoi apply --refresh-externals --force` flags, `.chezmoiremove`/`.chezmoiexternal.toml`, and troubleshooting — invoke it rather than re-deriving this from scratch.

## Commands

Preview and apply changes (run from anywhere; chezmoi finds the source dir automatically):

```bash
chezmoi diff                                  # preview pending changes before applying
chezmoi apply --refresh-externals --force     # apply — always use both flags (force avoids interactive prompts Claude can't answer)
chezmoi cat <file>                            # preview a rendered template's output
chezmoi execute-template '{{ .chezmoi.os }}'  # test a template snippet in isolation
chezmoi re-add <file>                         # pull an edited target file back into the source dir
chezmoi status                                # what's pending
```

Syncing to git (per README.md):

```bash
chezmoi cd            # cd into the source dir (this repo)
git add --all && git commit && git push
chezmoi update        # pull + apply on another machine
```

There is no build, lint, or test suite — this is a config repo. "Testing" a change means `chezmoi diff`/`chezmoi cat` to check rendering, then `chezmoi apply --refresh-externals --force` and exercising the shell/tool it affects.

## Architecture

- **`run_onchange_before_NN_*.sh`** — idempotent setup scripts chezmoi re-runs whenever their content hash changes, in numeric order (`0` installs apt packages, `1` sets zsh as default shell and installs antidote, `20`+ install individual tools: fzf, diff-so-fancy, vim-plug, tmux plugin manager, lazygit, fonts, difftastic, nbdime). New machine-setup steps should follow this pattern: a numbered `run_onchange_before_*.sh` with `set -euo pipefail` and an existence check so re-runs are no-ops.
- **`.chezmoi.toml.tmpl`** — chezmoi's own config template; prompts once for `github_email` and enables `autoCommit`/`autoPush` on `chezmoi apply` (so applying on a configured machine also commits/pushes to this repo — be aware of that when testing changes there).
- **`.commit_message.tmpl`** — template chezmoi uses to prompt for the commit message when autoCommit fires.
- **Shell startup chain**: `dot_zshrc` sources `bin/term-background` (must run before the p10k instant-prompt block, since it reads the tty for OSC 11 background detection) → p10k instant prompt → `~/.environment`(`dot_environment`) + optional `~/.environment.local` → `~/.aliases` (`dot_aliases`) + optional `~/.aliases.local` → antidote plugin load (plugin list in `dot_zsh_plugins.txt`) → `~/.p10k.zsh`. The `.local` files are gitignored, host-specific overrides — never add machine-specific values directly to the tracked files.
- **`dot_gitconfig.tmpl`** — templated on `.github_email`; wires up diff-so-fancy/difftastic as pagers and nbdime for Jupyter notebook diffing. `~/.gitconfig.local` (untracked) is included for machine-specific overrides.
- **`private_dot_config/`** → installs to `~/.config/` with restrictive permissions (nvim, matplotlib styles, fontconfig).
- **`bin/`** → installs to `~/bin/`; `executable_term-background` detects terminal light/dark background via OSC 11 for theme-matching in nvim etc.
- **`.chezmoiignore`** lists source-repo-only paths (`README.md`, `.claude`, `.codex`, `.agents`) that chezmoi should never install to `$HOME`.