1@README.md
2
3- **`launch.sh` must never build, wait, or enter `nix develop`.** Its whole
4  job is to answer inside the client's 30 s startup timeout on an empty
5  `buck-out`. Anything slow goes in `install.sh`.
6- **Nothing but JSON-RPC on `launch.sh`'s stdout.** Diagnostics go to stderr;
7  the one stdout line it may write itself is the error reply to
8  `initialize`. Same rule as the proxy's (`../../apps/native/CLAUDE.md`).
9- `run/bin/native` is a copy, not a symlink into `buck-out`, on purpose - see
10  the comment in `install.sh`. Do not "simplify" it into a symlink.
11- Test a change with `tools/mcp/test.sh`: scripted stdio, timed, in a bare
12  environment (`env -i PATH=/usr/bin:/bin`, all a profile-less NixOS process
13  gets), with and without a binary, against a scratch copy of the layout so
14  the real `run/bin` is never moved.
15- **`launch.sh` uses bash builtins only.** In that bare environment
16  `dirname`, `sed` and `jq` do not exist; a `dirname` there made the repo
17  root "" and the launcher looked for `//run/bin/native` (2026-09-21).
18- Keep both scripts shellcheck-clean: `nix develop -c shellcheck tools/mcp/*.sh`.