improve docs and general flow