polish generated schema and update docs