all repos — dot @ b9e58b099d2c9fca930f94f54fbfef0675a17974

Shell, editor and terminal configuration, and the tools that go with them 

tree-sitter-cli, and: a read-only clone hands back a change request

An https clone of this repo cannot push -- the host serves it anonymously and
refuses the push with a 403 -- and that is how a machine whose owner cannot
hold a key gets it. An agent troubleshooting there would edit a tracked file,
see the fix applied, and lose it at the next pull, or leave that clone unable
to fast-forward and quietly cut off from changes. CLAUDE.md now says how to
tell the two cases apart, and what to do instead: make it machine-local where a
hook covers it, or hand back a change request -- paths, the actual diff, why,
and how to verify -- stating that nothing was applied.

AGENTS.md is a symlink to CLAUDE.md, so the agents that look for that name get
the same file rather than a second copy to drift.

tree-sitter-cli: nvim-treesitter generates and compiles its parsers with it.
Igor Soarez igor@soarez.org
Tue, 22 Sep 2026 11:21:40 +0300
commit

b9e58b099d2c9fca930f94f54fbfef0675a17974

parent

f31a7a6d69713d45463d53765c9e39aa06290f8c

3 files changed, 33 insertions(+), 0 deletions(-)

jump to
A AGENTS.md 
@@ -0,0 +1,1 @@
+CLAUDE.md
M Brewfile → Brewfile 
@@ -29,6 +29,7 @@ brew "fswatch"             # bin/sz-wait-for
 brew "n"                   # node versions, under $N_PREFIX
 brew "bash-completion"
 brew "shellcheck"
+brew "tree-sitter-cli"     # nvim-treesitter generates and compiles parsers with it
 
 cask "alacritty"
 cask "hammerspoon"
M CLAUDE.md → CLAUDE.md 
@@ -48,6 +48,37 @@
 `~/.localenv` (every shell) and `~/.localprofile` (interactive) stay what they
 always were: per-host files written by hand, in no repo at all.
 
+## Can this machine push? Check before changing anything here
+
+`git remote -v` answers it:
+
+- `git@…` — ssh, so this clone can push, and a change made here can be
+  published.
+- `https://…` — **read-only**. The git host serves this repo anonymously over
+  https, and a push is refused: `fatal: unable to access … The requested URL
+  returned error: 403`. A machine that cannot hold a key -- one its owner does
+  not control, say -- is cloned this way on purpose.
+
+On a read-only clone, **do not edit tracked files.** Nothing committed there can
+leave the machine: the work is lost at the next pull, or the pull stops
+fast-forwarding and that machine quietly stops receiving changes. This is the
+trap for an agent troubleshooting on such a machine -- the fix looks applied,
+disappears, and the fault returns on the next machine that pulls.
+
+Do one of these instead:
+
+1. **Make it machine-local, where a hook covers it** (next section). Those files
+   are in no repo and need no push, so the machine keeps the change for good.
+2. **Otherwise, hand back a change request instead of editing.** Write it to be
+   pasted whole into a session on a machine that can push, and include:
+   - the repo-relative path of every file to change;
+   - the change itself -- a diff, or the exact replacement text. Not a
+     description of it;
+   - why, in a line or two: what was observed on this machine;
+   - how to verify it, and where.
+
+   Say plainly that it was not applied, and that this machine cannot publish it.
+
 ## Changing one machine only
 
 Every machine shares this repo, so a setting wanted on one of them does not