CLAUDE.md: where a single machine's changes go, and what to do without a hook

The hooks existed but were documented nowhere together: ~/.localenv and
~/.localprofile were mentioned in passing, the skip file under the link
system, and the ssh, git, Hammerspoon, Ghostty and Alacritty ones only in the
config files that read them. Anyone -- an agent especially -- asked to change
one machine had to read the whole repo to find out whether that was possible
without committing to it.

They are one table now, with what each overrides and what reads it, plus what
has no hook at all. And the rule for everything else: say what is being asked
for and where it would have to live, rather than putting one machine's
preference in the config every machine shares, or leaving that machine's
checkout dirty and its sync failing.

1 files changed, 29 insertions, 0 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
index 543698a..ce2dcff 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -48,6 +48,35 @@ what it needs through these, each of them optional and absent by default:
 `~/.localenv` (every shell) and `~/.localprofile` (interactive) stay what they
 always were: per-host files written by hand, in no repo at all.
 
+## Changing one machine only
+
+Every machine shares this repo, so a setting wanted on one of them does not
+belong in a tracked file here. Each of these is hand-written, read where the
+tracked config says so, and in no repo:
+
+| File | Overrides | Read by |
+|---|---|---|
+| `~/.localenv` | environment for every shell: PATH, exported variables. POSIX sh, no forks | `config/env`, before it drops `_env_prepend`/`_env_append`, so those work here |
+| `~/.localprofile` | interactive setup: aliases, prompt, anything that forks | `config/profile`, last |
+| `~/.config/ssh/config-local` | ssh, this host only. See `config/ssh/config-local-example` | `config/ssh/entry`, before the shared defaults |
+| `~/.config/git/config-local` | git, this host only -- the work identity, `includeIf` blocks. See `config/git/config-local-example` | `config/git/config`, after the `[user]` block above it, and git takes the last value |
+| `~/.config/hammerspoon/local.lua` | Hammerspoon: rebinding a hotkey set here shadows it | `config/hammerspoon/init.lua`, last, in a `pcall` |
+| `~/.config/ghostty-local` | Ghostty: later values replace earlier ones, `keybind` accumulates | `config/ghostty/config`, last, as an optional `config-file` |
+| `~/.local/share/alacritty/local.toml` | Alacritty | imported by `config/alacritty/alacritty.toml` |
+| `~/.config/dot/skip` | which `link/` parts this machine does not want, one name per line | `link/lib.sh`, as each part starts |
+
+Not covered today: nvim, tmux, bat, lsd, and `~/.claude/settings.json` -- which
+a machine can only leave alone entirely, by naming `claude` in the skip file.
+
+**When a request is not covered by the table, say so rather than editing a
+tracked file to suit one machine.** State the change that was asked for and
+where it would have to live, and let the owner choose: a new hook here is a
+deliberate change that every machine then carries, and is worth making when the
+need will recur -- the Hammerspoon, Ghostty and skip hooks all started that way.
+The wrong move is to quietly commit a machine's preference to the shared config,
+or to leave the machine's checkout dirty, which is how a host's sync starts
+failing.
+
 ## Automatic syncing
 
 On some machines a timer keeps this clone up to date: it rebases onto