update doc, add sanity checks to role alignment