soleprint/rig/docs/notes/cluster.md

ctrl/cluster.sh

Why list and free live here

list and free live in cluster.sh rather than in a separate script because a near-identical second name (cluster / clusters) is a trap — you reach for one and get the other. One target, one file, unambiguous subcommands.

Idempotent means convergent

"Idempotent" here means convergent, not "exits early if the cluster exists". That distinction matters: an interrupted first run can leave a cluster created but not finished, and returning early on the re-run would strand it there. The create step is conditional; every step after it always runs, and each one is individually idempotent.