hooks: reorganize and document
simplify validation