From 8344b9d5ff40b300a0022594fccc53d905a0e126 Mon Sep 17 00:00:00 2001
From: Daniel Bauer <github@dbauer.me>
Date: Sat, 8 Aug 2026 17:38:15 +0200
Subject: [PATCH] feat: add CLAUDE.md

---
 .chezmoiignore |  5 +++++
 .gitignore     |  1 +
 CLAUDE.md      | 43 +++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 49 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 CLAUDE.md

diff --git a/.chezmoiignore b/.chezmoiignore
index b43bf86..f3262ba 100644
--- a/.chezmoiignore
+++ b/.chezmoiignore
@@ -1 +1,6 @@
 README.md
+.claude
+.codex
+.agents
+CLAUDE.md
+CLAUDE.local.md
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..5eec986
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+.claude
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..a7e8068
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,43 @@
+# 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`.