For agents, on top of README.md, which they read first.

Notes for agents

A new command is a task in mise.toml first. A script goes here only when the task needs logic; the task still exists and is what a README, hk.pkl or another task names. Do not document a bare script path as the way to run something.

Never write a version in a second file without adding it to check-versions.sh. mise.toml is the one place; hk.pkl's amends line is the one repeat, and the check is why it cannot drift.

with-secrets.sh must never print, log or write the key, and must keep the plain path working with no fnox installed: fnox is optional, the environment is the contract.

Scripts here use bash and POSIX tools only. No nix, no host-specific helper, no tool that mise.toml does not install; cd "$(dirname "$0")/.." first, so they run from any directory.

Where claude is a wrapper script (a nix wrapper is one), claude plugin test refuses it. Pass the inner binary: CLAUDE=<store path>/bin/claude mise run plugin:test (see plugin/tests/CLAUDE.md).