hammerspoon, ghostty: example files for their machine-local configs

ssh and git each ship one; these two hooks were discoverable only by reading
the config that loads them. Both examples carry what is easy to get wrong:
init.lua's hotkey() helper and mod tables are locals, so a local.lua calls
hs.hotkey.bind directly, and a binding there can only be shadowed, never
deleted; in Ghostty a single-value key replaces while keybind accumulates, and
`ignore` is how a binding is switched off rather than added to.

Checked rather than assumed: the lua parses, and the Ghostty example validates
and, dropped in as ~/.config/ghostty-local, does what it says -- font-size,
command and background-opacity replaced, super+shift+n added, alt+enter turned
off.

3 files changed, 56 insertions, 2 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
index ce2dcff..546678f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -60,8 +60,8 @@ tracked config says so, and in no repo:
 | `~/.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` |
+| `~/.config/hammerspoon/local.lua` | Hammerspoon: rebinding a hotkey set here shadows it. See `config/hammerspoon/local-example.lua` | `config/hammerspoon/init.lua`, last, in a `pcall` |
+| `~/.config/ghostty-local` | Ghostty: later values replace earlier ones, `keybind` accumulates. See `config/ghostty/ghostty-local-example` | `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 |
 
diff --git a/config/ghostty/ghostty-local-example b/config/ghostty/ghostty-local-example
new file mode 100644
index 0000000..98bdb02
--- /dev/null
+++ b/config/ghostty/ghostty-local-example
@@ -0,0 +1,25 @@
+# Example ~/.config/ghostty-local: Ghostty for one machine only.
+#
+# Not linked and never synced -- write it by hand where it is wanted. It cannot
+# sit beside this file: link.sh links this whole directory, so ~/.config/ghostty
+# is the checkout itself. config/ghostty/config reads it last, as an optional
+# `config-file`, so a machine without one is not an error.
+#
+# Read last means: a single-value key here replaces the one set there, the
+# theme's colours included; `keybind` accumulates instead, so a binding here is
+# added to those. Reload with cmd-shift-, or restart Ghostty.
+
+# Single-value keys replace.
+font-size = 14
+background-opacity = 0.95
+
+# Start a plain shell instead of the tmux session config/ghostty/config asks
+# for. --login runs ~/.zprofile, which is what restores PATH order after macOS
+# rebuilds it; -i runs ~/.zshrc, for the prompt, keybindings and completions.
+command = /bin/zsh --login -i
+
+# keybind accumulates, so this is added to the ones already set.
+keybind = super+shift+n=new_window
+
+# To switch one off rather than add: bind it to `ignore`.
+keybind = alt+enter=ignore
diff --git a/config/hammerspoon/local-example.lua b/config/hammerspoon/local-example.lua
new file mode 100644
index 0000000..2ddfe15
--- /dev/null
+++ b/config/hammerspoon/local-example.lua
@@ -0,0 +1,29 @@
+-- Example ~/.config/hammerspoon/local.lua: Hammerspoon for one machine only.
+--
+-- Not linked and never synced -- write it by hand where it is wanted. Only
+-- init.lua is linked into ~/.config/hammerspoon, so a file beside it there is
+-- the machine's own and in no repo. init.lua loads it last, inside a pcall: it
+-- can override anything set there, and a mistake in it is reported without
+-- taking the rest of the config down.
+--
+-- Reload with ctrl-shift-alt-h, as with any other change.
+--
+-- Note what is NOT available here: init.lua's `hotkey()` helper and its mod
+-- tables (cs, ca, csa, cag, hyp) are locals of that file, and this is a
+-- separate chunk. Call hs.hotkey.bind directly and write the modifiers out.
+
+-- Take a key over. Binding a combination init.lua already bound wins, because
+-- hs.hotkey stacks bindings per combination and this one is enabled last.
+hs.hotkey.bind({ "ctrl", "alt" }, "1", function()
+    hs.application.launchOrFocus("Slack")
+end)
+
+-- Give a key back to the OS or another app: bind it to nothing. A binding from
+-- init.lua cannot be deleted from here -- it keeps no reference to the hotkey
+-- object -- so shadowing it with a no-op is how it is switched off.
+hs.hotkey.bind({ "ctrl", "alt", "cmd" }, "0", function() end)
+
+-- Anything else Hammerspoon can do belongs here just as well.
+hs.hotkey.bind({ "ctrl", "alt" }, "m", function()
+    hs.alert.show(hs.host.localizedName())
+end)