Brew's fennel formula now ships fennel.lua under 5.1/ and 5.5/ but not
5.4/, which Hammerspoon embeds. Install fennel via luarocks pinned to
lua@5.4 instead.

Assisted-by: Claude Opus 4.6 via Claude Code

diff --git a/.hammerspoon/init.lua b/.hammerspoon/init.lua
index c7165e5f..801021fd 100644
--- a/.hammerspoon/init.lua
+++ b/.hammerspoon/init.lua
@@ -1,4 +1,5 @@
--- Handle mismatch between homebrew's version of Lua and hammerspoon's version
+-- Hammerspoon embeds Lua 5.4 but brew's lua tracks the latest version.
+-- Use luarocks to find packages installed for the right Lua version.
 local lVer = _VERSION:match("Lua (.+)$")
 local luarocks = "/opt/homebrew/bin/luarocks"
 package.path = package.path .. ";" .. hs.execute(
diff --git a/Brewfile b/Brewfile
index 2b2dd1c0..d115e13d 100644
--- a/Brewfile
+++ b/Brewfile
@@ -10,6 +10,7 @@ brew "eza"
 brew "ffmpeg"
 brew "git"
 brew "jj"
+brew "lua@5.4"
 brew "luarocks"
 brew "mas"
 brew "restic"
diff --git a/README.md b/README.md
index 55946d30..136704f0 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,30 @@
 This repo contains both my dotfiles as well as [Ansible][ansible] playbooks to
 provision new machines.
 
-## Useful Commands
+## Hammerspoon and Fennel
+
+Hammerspoon embeds Lua 5.4, but Homebrew's `lua` formula tracks the latest
+version (currently 5.5). Fennel must be installed for the right Lua version
+or Hammerspoon won't find it.
+
+The `frork` provisioner handles this automatically. To set it up manually:
+
+```sh
+brew install lua@5.4 luarocks
+
+# Point luarocks at the 5.4 interpreter.
+luarocks --lua-version=5.4 --local config variables.LUA /opt/homebrew/opt/lua@5.4/bin/lua
+luarocks --lua-version=5.4 --local config variables.LUA_DIR /opt/homebrew/opt/lua@5.4
+
+# Install fennel for Lua 5.4.
+luarocks --lua-version=5.4 --local install fennel
+```
+
+`init.lua` uses `luarocks path` to add the correct directories to
+`package.path` at runtime, so Hammerspoon finds fennel regardless of which Lua
+version Homebrew defaults to.
+
+## Useful commands
 
 ```
 # Adding a submodule
diff --git a/frork/_macos.fnl b/frork/_macos.fnl
index 593413b9..83b87047 100644
--- a/frork/_macos.fnl
+++ b/frork/_macos.fnl
@@ -43,5 +43,14 @@
 
 (ok :dock)
 
+;; Hammerspoon uses Lua 5.4, but brew's lua formula tracks the latest
+;; version. Configure luarocks to find lua@5.4 and install fennel there
+;; so Hammerspoon can require it.
+(sh! :luarocks :--lua-version=5.4 :--local :config :variables.LUA
+     :/opt/homebrew/opt/lua@5.4/bin/lua)
+(sh! :luarocks :--lua-version=5.4 :--local :config :variables.LUA_DIR
+     :/opt/homebrew/opt/lua@5.4)
+(sh! :luarocks :--lua-version=5.4 :--local :install :fennel)
+
 ;; TODO
 ;; - install numderline fonts