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).

screenshots.sh must never show the account of whoever runs it. The session reads no user settings, and shot drops the rows Claude Code draws about plan usage (the first 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 uses git -C and never cd: every command after a cd that failed would run in this repository, which is how two junk commits were once made here (2026-10-06).

Press Enter on a dialog only after the screen shows the choice you mean. The trust dialog opens on "No, exit"; a Down sent before it is ready is lost, and Enter then ends the session.