some more specs and readme fix