also updated some really bit-rotted docs we will deprecate the docs/ directory soon, they are wrong and misleading at this point.