docs: add explanation of modes

should we wait to merge until we remove this mode?