add notes about how this is supposed to work