[WIP] Corrections and improvements

unfinished

fixes: #1, #2, #3, #4

also
adds notes on upgrading - to be improved still
restructure to create psr-4 structured modules