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

Notes for agents

Score a new revision when it lands. After adding a revision and its song.js, run op-env-run -- node tools/critic/critic.mjs --write --song <theme>/<song> and commit the frontmatter with the revision. Only unscored revisions are called, unless --all is given.

Never copy the rubric. It lives in website/src/jev/critic.mjs, shared with the REPL. A reworded copy gives numbers that don't compare with the recorded ones. To change a criterion or a step, change the module, bump RUBRIC, and rescore everything with --all. Check the spread on controls first (three notes, a one-bar loop) before recording: the old yes/no question gave every song 93-96%.

Record means, not one call. A recorded score is meanVerdict (website/src/jev/critic.mjs) over --runs calls, default 3; keep artRuns beside every mean so the spread stays visible. Don't record from --runs 1 except to test the tool: one call is the noise this replaced.

Edits are surgical. The script rewrites only art:/artRuns: lines and the critic: block (setRevisionArt, setCritic in website/src/jev/critic.mjs, tested in critic.test.mjs), keeping the frontmatter's quoting and comments (# overwritten by rev 2). Don't switch it to a YAML parse-and-dump, which would reformat every spec.

Never guess an unrecoverable revision. When git doesn't hold a revision's code, the record is art: null # not scored: ….

The key stays in the environment. Run under op-env-run. Never capture the key with op-env-run -- printenv (1Password masks it as <concealed by 1Password>), never print it, and never write it down.