feat(config): T-1261 — reach is a bare name on PATH, in every context

`uv tool install --editable` puts the executable in ~/.local/bin rather than
.venv/bin, which is the difference between a command that works everywhere and
one that works only under an activated venv. Agents and git hooks never
activate one.

Verified in the three contexts that matter, with a negative control so the
passes discriminate: a stripped non-interactive shell, a REAL git hook process
(via git -c core.hooksPath ... hook run pre-push, not a simulation), and an
agent Bash call — all with VIRTUAL_ENV unset. With ~/.local/bin removed from
PATH the same check reports NOT-FOUND, so this is not passing because a venv
happens to be active.

Found a silent interpreter fork while doing it, which is this initiative's own
failure mode wearing a different hat. uv tool install without --python picked
CPython 3.11 for the tool environment while .venv and system python are 3.14 —
uv selects the lowest interpreter satisfying requires-python. reach would have
run on one interpreter and the test scripts on another, with different wheels
for numpy/scipy/PIL, and future 3.12+ syntax would break the tool while the
venv stayed green. PYTHON_VERSION now pins both.

make setup-venv is rebuilt on uv, per the T-1258 finding that it called
.venv/bin/pip against a venv that has no pip. The first fix was wrong too:
plain `uv venv` fails on an existing venv, so the target was not idempotent
where the version it replaced had been. Caught by running it twice instead of
dry-running it — which is how the original rotted unnoticed.

make install-reach self-checks that reach is actually on PATH afterwards
rather than assuming it. make reach-repoint gives a name to the situation
where uv keeps resolving a deleted worktree: reach still runs, edits in the
main checkout do nothing, and there is no error message.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs/DEVOPS.md

@@ -50,6 +50,41 @@ GODOT_VERSION=4.4 make setup      # Pin a specific Godot version
 
 Downloads and installs Godot to `~/bin/godot4`, installs Rust clippy + rustfmt, and verifies Python/curl/unzip. Skips the download if the correct version is already installed. The `GODOT_VERSION` variable defaults to `4.6` and can be overridden.
 
+#### The `reach` CLI and PATH (T-1261, D-263)
+
+```bash
+make install-reach                # Put `reach` on PATH (run by `make setup`)
+make reach-repoint                # Re-point `reach` at THIS checkout
+```
+
+`reach` is installed with `uv tool install --editable`, which puts the
+executable in `~/.local/bin` rather than `.venv/bin`. **That distinction is the
+whole point.** A `[project.scripts]` entrypoint alone lands in `.venv/bin`,
+which is on PATH only while the venv is activated — and agents and git hooks
+never activate it. Installing as a uv tool makes `reach` a bare name in every
+context: interactive shell, git hook, agent `Bash` call.
+
+**Always invoke it as the bare word `reach`.** Never `python -m tooling`, never
+`.venv/bin/reach`, never an absolute path. Any of those breaks the
+`Bash(reach *)` permission rule and prompts every time — the same failure `tea`
+had, where the fix was a bare name on PATH — and reintroduces the interpreter
+fork between a human shell and a hook.
+
+`--editable` means the checkout *is* the source: edit `tooling/`, run `reach`,
+no reinstall. `--python` is pinned to `PYTHON_VERSION` so the tool and `.venv`
+share one interpreter; left to itself uv picks the lowest version satisfying
+`requires-python`, which silently forks the two environments.
+
+**Re-pointing.** uv records the source path at install time. An install made
+from a worktree keeps resolving there after the worktree is deleted — `reach`
+then still runs, but from a path that no longer exists or, worse, from a stale
+copy, so edits in the main checkout appear to do nothing. There is no error
+message for this. Run `make reach-repoint` from the checkout you want it to
+follow.
+
+Activating `.venv` is still needed for running the test scripts directly; it is
+not needed for `reach`.
+
 ### Build
 
 ```bash