more docs, spec, ready for 1.0.0 :musical_note: