1@README.md
2
3## Notes for agents
4
5**A new command is a task in `mise.toml` first.** A script goes here only when the task
6needs logic; the task still exists and is what a README, `hk.pkl` or another task
7names. Do not document a bare script path as the way to run something.
8
9**Never write a version in a second file without adding it to `check-versions.sh`.**
10`mise.toml` is the one place; `hk.pkl`'s `amends` line is the one repeat, and the
11check is why it cannot drift.
12
13**`with-secrets.sh` must never print, log or write the key,** and must keep the plain
14path working with no fnox installed: fnox is optional, the environment is the
15contract.
16
17**Scripts here use bash and POSIX tools only.** No nix, no host-specific helper, no
18tool that `mise.toml` does not install; `cd "$(dirname "$0")/.."` first, so they run
19from any directory.
20
21**Where `claude` is a wrapper script (a nix wrapper is one), `claude plugin test`
22refuses it.** Pass the inner binary: `CLAUDE=<store path>/bin/claude mise run plugin:test` (see
23`plugin/tests/CLAUDE.md`).
24
25**`screenshots.sh` must never show the account of whoever runs it.** The session reads
26no user settings, and `shot` drops the rows Claude Code draws about plan usage (the
27first full run put the runner's plan usage and timezone in a picture). After any change, read the four SVGs before committing them. It also
28uses `git -C` and never `cd`: every command after a `cd` that failed would run in this
29repository, which is how two junk commits were once made here (2026-10-06).
30
31**Press Enter on a dialog only after the screen shows the choice you mean.** The trust
32dialog opens on "No, exit"; a Down sent before it is ready is lost, and Enter then
33ends the session.