refine & document debug mode