[pl] fix false alarms, add docs